Overview
RESTful API for the Bulgarian Commercial Register
Additional Developer Resources
LLM Context Files: For developers using AI assistants (like Claude, ChatGPT, and others), we provide context files: llms.txt (short version) and llms-full.txt (full documentation). These files can be loaded into AI models for better integration and understanding of the API structure.
REST API for accessing data on over 1,300,000 Bulgarian companies. Free account API keys include regular search, company and person lookups, and 100 requests/day. Pro subscriptions unlock Pro company search filters, financial sorting, latest financial-year data, and higher limits.
Key Features
Authentication
Customer API requests require a valid API key. Free accounts can create an API key; Pro subscriptions unlock Pro API features. Pass the key via HTTP header:
X-API-Key: your_api_key_here 1. Register for free at companybook.bg/sign-up
2. Get your API key from your account
Daily Request Limits
Response Format
All responses are in JSON format with a consistent structure:
{
"results": [...],
"total": 1234
} Data Models
Structure of objects returned by the API
Company
Basic data (with_data=false)
{
"uic": "123456789", // Company UIC (ЕИК)
"name": "Example Ltd", // Name
"legalForm": "ООД", // Legal form
"status": "N", // Status (N = active, L = liquidated)
"transliteration": "Example OOD" // Transliteration
} Full data (with_data=true)
{
"company": {
// Basic information
"id": "507f1f77bcf86cd799439011",
"uic": "123456789",
"companyName": {
"name": "Example Ltd",
"name_tags": ["exa", "xam"]
},
"companyNameTransliteration": {
"name": "Example OOD",
"name_tags": ["exa", "xam"]
},
"legalForm": "Дружество с ограничена отговорност",
"status": "N",
// Addresses
"seat": {
"country": "България",
"region": "София",
"district": "София (столица)",
"municipality": "София",
"settlement": "София",
"area": "Център",
"street": "ул. Витоша",
"streetNumber": "15",
"block": "2",
"entrance": "А",
"floor": "3",
"apartment": "5",
"postCode": "1000",
"districtid": 1
},
"correspondenceSeat": { /* същата структура */ },
// Contacts
"contacts": {
"email": "contact@example.com",
"phone": "+359 2 123 4567",
"fax": "+359 2 123 4568",
"website": "https://example.com"
},
// Activity
"subjectOfActivity": "Консултантски услуги",
"nkids": [
{
"code": "62.02",
"description": "Дейности в областта на информационните технологии",
"id": "nkid123"
}
],
// Management
"managers": [
{
"name": "Иван Петров",
"indent": "1234567890",
"address": "София, ул. Витоша 1"
}
],
"representatives": [ /* същата структура */ ],
"boardOfDirectors": [ /* същата структура */ ],
// Financial information
"capital": {
"amount": "2000",
"currency": "BGN",
"paidAmount": "2000"
},
// Ownership
"partners": [
{
"person": {
"name": "Иван Петров",
"indent": "1234567890",
"address": "София"
},
"liabilityType": "ограничена",
"contribution": "1000 BGN"
}
],
// VAT registration
"registerInfo": {
"name": "Example Ltd",
"vat": "BG123456789",
"address": "София, ул. Витоша 1",
"registrationDate": "2020-01-15"
},
// Metadata
"lastUpdated": "2024-01-15T10:30:00Z"
},
// Change history
"history": [
{
"deedUIC": "123456789",
"timestamp": "2024-01-15T10:30:00Z",
"changeType": "address_change",
"field": "seat.address",
"oldValue": "ул. Стара 5",
"newValue": "ул. Витоша 1"
}
],
// Subsidiaries
"daughters": [
{
"uic": "987654321",
"company_name": {
"name": "Subsidiary Ltd"
},
"roles": [
{
"position": "Manager",
"from": "2022-05-01",
"until": null,
}
]
}
]
} Note: Full data contains all available fields for the company.
Some fields may be missing depending on available information.
Person
Basic data (with_data=false)
{
"id": "507f1f77bcf86cd799439011", // Unique identifier
"name": "Иван Петров", // Person's name
"indent": "aaaaxxxxxxxxxxxxxxxx", // Indent/
"companies": 3 // Number of related companies
} Full data (with_data=true)
{
"_id": "507f1f77bcf86cd799439011",
"indent": "1234567890",
"name": "Иван Петров",
"nameTags": ["иван", "петров", "ivan", "petrov"],
// All companies the person is involved in
"personCompanies": [
{
"uic": "123456789",
"legalForm": "Дружество с ограничена отговорност",
"share": "50.00", // Share in the company (if a partner)
"company_name": {
"name": "Example Ltd",
"name_tags": ["example", "ltd"]
},
"roles": [
{
"position": "Manager", // Position / role
"from": "2020-01-15", // From date
"until": null, // To date (null = active)
},
{
"position": "Partner",
"from": "2020-01-15",
"until": null,
"share": 50
}
]
},
{
"uic": "987654321",
"company_name": {
"name": "Another Company"
},
"roles": [
{
"position": "BoardMember",
"from": "2021-03-10",
"until": "2023-12-31", // Inactive role
"share": null
}
]
}
]
} personCompanies explanation:
- position: Role in the company (manager, partner, board member, etc.)
- from/until: Validity period of the role
- share: Share in the company (for partners/shareholders)
- Active roles: until = null means the role is still active
Unified Search
{
"companies": [
{
"uic": "123456789",
"name": "Example Ltd",
"legalForm": "ООД",
"status": "N",
"transliteration": "Example OOD"
}
],
"people": [
{
"id": "507f1f77bcf86cd799439011",
"name": "Иван Петров",
"indent": "1234567890",
"companies": 3
}
]
} Data Type Information
Company Status
| Code | Description |
|---|---|
N | Active company |
E | Active company (EOOD) |
L | Liquidated |
C | Deleted |
Legal Forms
| Form | Description |
|---|---|
| ООД | Limited Liability Company |
| ЕООД | Single-member Limited Liability Company |
| АД | Joint Stock Company |
| ЕТ | Sole Trader |
| СД | General Partnership |
| КД | Limited Partnership |
| ЕАД | Single-member Joint Stock Company |
| Фондация | Foundation |
| Сдружение | Association |
District Codes
| ID | District |
|---|---|
1 | София (столица) |
31 | Бургас |
32 | Варна |
45 | Пловдив |
30 | Благоевград |
33 | Велико Търново |
34 | Видин |
35 | Враца |
36 | Габрово |
37 | Добрич |
38 | Кърджали |
39 | Кюстендил |
40 | Ловеч |
41 | Монтана |
42 | Пазарджик |
43 | Перник |
44 | Плевен |
46 | Разград |
47 | Русе |
48 | Силистра |
49 | Сливен |
50 | Смолян |
51 | София |
52 | Стара Загора |
53 | Търговище |
54 | Хасково |
55 | Шумен |
56 | Ямбол |
Companies
API endpoints for working with companies
Get Company by UIC
Retrieve detailed information about a specific company.
/api/companies/:uic Parameters
Response
Basic data (with_data=false):
{
"uic": "123456789",
"name": "Example Ltd",
"legalForm": "ООД",
"status": "N",
"transliteration": "Example OOD"
} Full data (with_data=true):
{
"company": { /* пълни данни */ },
"history": [ /* история */ ],
"daughters": [ /* дъщерни фирми */ ]
} Code Examples
// Get a company by UIC (ЕИК)
async function getCompany(uic, withData = false) {
const response = await fetch(
`https://api.companybook.bg/api/companies/${uic}?with_data=${withData}`,
{
headers: { "X-API-Key": "your_api_key_here" }
}
);
return await response.json();
}
// Usage examples
// Basic data
const basicData = await getCompany("{uic}");
// Full data (includes history, subsidiaries)
const fullData = await getCompany("{uic}", true); import requests
API_KEY = "your_api_key_here"
HEADERS = {"X-API-Key": API_KEY}
# Получаване на юридическо лице по ЕИК
def get_company(uic, with_data=False):
response = requests.get(
f"https://api.companybook.bg/api/companies/{uic}",
params={"with_data": str(with_data).lower()},
headers=HEADERS
)
return response.json()
# Примери за използване
basic_data = get_company("{uic}")
full_data = get_company("{uic}", True) # Получаване на юридическо лице с основни данни
curl "https://api.companybook.bg/api/companies/{uic}" \
-H "X-API-Key: your_api_key_here"
# Получаване на юридическо лице с пълни данни (история, дъщерни фирми)
curl "https://api.companybook.bg/api/companies/{uic}?with_data=true" \
-H "X-API-Key: your_api_key_here" Search Companies
Search for companies with regular filters using any valid API key. Pro financial filters, registration filters, and financial sorting require a paid API key.
/api/v2/companies/search Free account API keys can use regular search parameters. Paid API keys can also use Pro financial and registration filters, plus financial sorting.
Search returns at most the first 1000 ranked matches. Counts above that are shown as 1000+.
Company search returns lean search rows. Use GET /api/companies/{uic}?with_data=true for full company details.
Regular Search Parameters
| Parameter | Type | Description |
|---|---|---|
| uic | string | Exact UIC |
| name | string | Company name |
| district | string | District ID |
| status | boolean | Active/inactive |
| legal_form | string | Legal form |
| nkid | string | Filter by business activity code (NKID), e.g. 47.11 |
| vat | boolean | VAT registration status |
| has_contact_data | boolean | Companies with contact data |
| limit | integer | Number of results |
| offset | integer | Pagination offset within the first 1000 matches |
Pro Search Parameters (paid API key required)
| Parameter | Type | Description |
|---|---|---|
| has_active_financial_data | boolean | Companies with active-year financial data |
| revenue_range | string | Public revenue bucket: 0, 0_100k, 100k_1m, 1m_5m, 5m_15m, 15m_40m, 40m_100m, 100m_plus |
| registration_year_from | integer | Registration year lower bound. Includes companies with only year precision. |
| registration_year_to | integer | Registration year upper bound. Includes companies with only year precision. |
| registration_date_from | string | Registration date lower bound. Use YYYY-MM-DD. Matches only companies with full day/month/year precision. |
| registration_date_to | string | Registration date upper bound. Use YYYY-MM-DD. Matches only companies with full day/month/year precision. |
| sort_by | string | Sort field: revenue, net_profit, accounting_profit, assets, equity, ebitda |
| sort_dir | string | Sort direction: asc or desc |
Response
{
"results": [
{
"uic": "123456789",
"name": "Example Ltd",
"legalForm": "ООД",
"status": "N",
"district": "София",
"transliteration": "Example Ltd",
"vatRegistered": true,
"contactPresence": {
"email": true,
"phone": true,
"website": true
},
"activeFinancialYear": 2024,
"latestRevenue": "1M - 5M"
}
],
"total": "1000+",
"totalCount": 1000,
"hasMoreTotal": true,
"limit": 20,
"offset": 0
} Search Examples
// Search companies
async function searchCompanies(params) {
const queryString = new URLSearchParams(params).toString();
const response = await fetch(
`https://api.companybook.bg/api/v2/companies/search?${queryString}`,
{
headers: { "X-API-Key": "your_api_key_here" }
}
);
return await response.json();
}
// Free API key: standard filters
const activeCompanies = await searchCompanies({
name: "Example",
status: true,
limit: 20
});
// Paid API key: premium registration and financial filters
const premiumCompanies = await searchCompanies({
registration_year_from: 2020,
revenue_range: "1m_5m",
sort_by: "revenue",
sort_dir: "desc",
limit: 20
}); # Търсене на фирми
def search_companies(**params):
response = requests.get(
"https://api.companybook.bg/api/v2/companies/search",
params=params,
headers=HEADERS
)
return response.json()
# Безплатен API ключ: обичайни филтри
active_companies = search_companies(
name="Example",
status=True,
limit=20
)
# Платен API ключ (Pro): регистрационни и финансови филтри
premium_companies = search_companies(
registration_year_from=2020,
revenue_range="1m_5m",
sort_by="revenue",
sort_dir="desc",
limit=20
) # Безплатен API ключ: търсене по име и статус curl "https://api.companybook.bg/api/v2/companies/search?name=Example&status=true" \ -H "X-API-Key: your_api_key_here" # Платен API ключ: търсене по година на регистрация curl "https://api.companybook.bg/api/v2/companies/search?registration_year_from=2020®istration_year_to=2024&limit=20" \ -H "X-API-Key: your_api_key_here" # Платен API ключ: търсене по публичен диапазон на приходи със сървърно сортиране curl "https://api.companybook.bg/api/v2/companies/search?revenue_range=1m_5m&sort_by=revenue&sort_dir=desc&limit=20" \ -H "X-API-Key: your_api_key_here"
People
API endpoints for working with people
Get Person by Identifier
Retrieve detailed information about a specific person.
/api/people/:indent Parameters
Response
Basic data (with_data=false):
{
"id": "507f1f77bcf86cd799439011",
"name": "Иван Петров",
"indent": "1234567890",
"companies": 3
} Full data (with_data=true):
{
"_id": "507f1f77bcf86cd799439011",
"indent": "1234567890",
"name": "Иван Петров",
"personCompanies": [ /* всички фирми */ ],
"nameTags": [ /* тагове */ ]
} Code Examples
// Get a person by identifier
async function getPerson(indent, withData = false) {
const response = await fetch(
`https://api.companybook.bg/api/people/${indent}?with_data=${withData}`,
{
headers: { "X-API-Key": "your_api_key_here" }
}
);
return await response.json();
}
// Basic data
const basicData = await getPerson("{indent}");
// Full data (includes all companies)
const fullData = await getPerson("{indent}", true); import requests
API_KEY = "your_api_key_here"
HEADERS = {"X-API-Key": API_KEY}
# Получаване на лице по идентификатор
def get_person(indent, with_data=False):
response = requests.get(
f"https://api.companybook.bg/api/people/{indent}",
params={"with_data": str(with_data).lower()},
headers=HEADERS
)
return response.json()
basic_data = get_person("{indent}")
full_data = get_person("{indent}", True) # Получаване на лице с основни данни
curl "https://api.companybook.bg/api/people/{indent}" \
-H "X-API-Key: your_api_key_here"
# Получаване на лице с пълни данни (всички фирми)
curl "https://api.companybook.bg/api/people/{indent}?with_data=true" \
-H "X-API-Key: your_api_key_here" Search People
Search for people by name. The v2 search endpoint accepts any valid free or paid API key.
/api/v2/people/search Free and paid API keys can use the v2 people search endpoint.
Two-token person searches are optimized for first-name plus family-name matching, with normal tokenized and fuzzy fallback.
Query Parameters
name * string Person name with_data boolean Full data limit integer Number of results offset integer Pagination offset within the first 1000 matches Response
{
"results": [
{
"id": "507f1f77bcf86cd799439011",
"name": "Иван Петров",
"indent": "1234567890",
"companies": 3
}
],
"total": "42",
"totalCount": 42,
"hasMoreTotal": false,
"limit": 20,
"offset": 0
} Search Examples
// Search people
async function searchPeople(name, limit = 20) {
const response = await fetch(
`https://api.companybook.bg/api/v2/people/search?name=${encodeURIComponent(name)}&limit=${limit}`,
{
headers: { "X-API-Key": "your_api_key_here" }
}
);
return await response.json();
}
const people = await searchPeople("Иван Петров"); # Търсене на лица
def search_people(name, limit=20):
response = requests.get(
"https://api.companybook.bg/api/v2/people/search",
params={"name": name, "limit": limit},
headers=HEADERS
)
return response.json()
people = search_people("Иван Петров") # Търсене на лица по име curl "https://api.companybook.bg/api/v2/people/search?name=Иван" \ -H "X-API-Key: your_api_key_here" # Търсене с лимит curl "https://api.companybook.bg/api/v2/people/search?name=Петров&limit=30" \ -H "X-API-Key: your_api_key_here"
Financial Data API
Endpoints for retrieving company financial information
Data Models
TypeScript interfaces for financial data structures.
FinancialData
interface FinancialData {
// Keyed by fiscal year - contains only the requested year
data: Record<string, YearData>;
// Fiscal years that require a paid plan
paid_data_years: string[];
} YearData
interface YearData {
income_statement: IncomeStatement;
balance_sheet: BalanceSheet;
general_info: GeneralInfo;
} IncomeStatement
interface IncomeStatement {
revenue: {
total: number;
net_total: number;
};
expenses: {
operating: number;
materials_and_services: number;
personnel: number;
depreciation_and_amortization: number;
interest_and_other_financial_expenses: number;
other: number;
total: number;
accounting_profit: number;
tax: number;
profit: number;
};
} BalanceSheet
interface BalanceSheet {
assets: {
intangible: number;
property_plant_equipment: number;
long_term_financial: number;
non_current: number;
inventories: number;
accounts_receivable: number;
current: number;
cash_and_equivalents: number;
total: number;
};
liabilities: {
equity: number;
retained_earnings: number;
total_exp: number;
total_liabilities: number;
current_liab: number;
financial_institutions_debt: number;
trade_payables: number;
other: number;
};
} GeneralInfo
interface GeneralInfo {
// Core metrics — all monetary values are in THOUSANDS of BGN
revenue: number;
profit: number;
accounting_profit: number; // profit before tax
tax: number; // corporate income tax
operating_expenses: number;
personnel_expenses: number;
total_assets: number;
equity: number;
retained_earnings: number;
// Asset breakdown
intangible: number;
tangible: number;
non_current: number;
current: number;
accounts_receivable: number;
// Calculated ratios — returned as DECIMAL FRACTIONS, not percentages
// (e.g. roa 0.157 means 15.7%). Multiply by 100 to display a percentage.
roa: number; // Return on Assets (fraction, e.g. 0.157)
profit_margin: number; // Net Profit Margin (fraction, e.g. 0.135)
operating_margin: number; // Operating Margin (fraction)
roe: number; // Return on Equity (fraction, e.g. 0.225)
current_ratio: number; // Current Assets / Current Liabilities
equity_ratio: number; // Equity / Total Assets (financial autonomy, fraction)
ebitda: number; // Earnings Before Interest, Taxes, Depreciation and Amortization (thousands BGN)
} Get Company Financial Data
Retrieve the financial information of a company for a single fiscal year, including income statement, balance sheet and key financial ratios. The fiscal year is selected with the required year parameter and the response contains only that year.
/api/companies/:uic/financial?year=YYYY Parameters
Authentication
Access Control
Daily Quota
Financial data is metered as distinct company-and-year combinations. Every new combination requested during the day consumes one unit of your daily allowance, and the size of the allowance depends on your plan:
Response Structure
// GET /api/companies/123456789/financial?year=2023
{
"data": {
"2023": {
"income_statement": { ... },
"balance_sheet": { ... },
"general_info": {
// NOTE: all monetary values are in THOUSANDS of BGN.
// revenue 12800 = 12,800,000 BGN.
"revenue": 12800,
"profit": 1730,
"accounting_profit": 1922,
"tax": 192,
// ratios are decimal fractions (0.135 = 13.5%)
"roa": 0.157,
"profit_margin": 0.135,
"roe": 0.225,
// ... други показатели
}
}
},
"paid_data_years": ["2024", "2025"]
} Code Examples
// Get a company's financial data for one year
async function getCompanyFinancial(uic, year) {
const response = await fetch(
`https://api.companybook.bg/api/companies/${uic}/financial?year=${year}`,
{
headers: { "X-API-Key": "your_api_key_here" }
}
);
return await response.json();
}
const financialData = await getCompanyFinancial("123456789", 2023);
// The response contains only the requested year
const year2023 = financialData.data["2023"];
console.log("Приходи 2023:", year2023.general_info.revenue);
console.log("Платени години:", financialData.paid_data_years); import requests
API_KEY = "your_api_key_here"
HEADERS = {"X-API-Key": API_KEY}
# Получаване на финансови данни на компания за една година
def get_company_financial(uic, year):
response = requests.get(
f"https://api.companybook.bg/api/companies/{uic}/financial",
params={"year": year},
headers=HEADERS
)
return response.json()
financial_data = get_company_financial("123456789", 2023)
year_2023 = financial_data["data"]["2023"]
print("Приходи 2023:", year_2023["general_info"]["revenue"])
print("Платени години:", financial_data["paid_data_years"]) # Получаване на финансови данни за компания за 2023 г. curl "https://api.companybook.bg/api/companies/123456789/financial?year=2023" \ -H "X-API-Key: your_api_key_here" # С BG префикс curl "https://api.companybook.bg/api/companies/BG123456789/financial?year=2022" \ -H "X-API-Key: your_api_key_here"
Errors
Error responses returned by this endpoint.
| Status | Code | Meaning |
|---|---|---|
| 400 | fiscalYearRequired | The year parameter is missing. |
| 400 | invalidFiscalYear | The year parameter is not a valid four-digit year. |
| 403 | financialSubscriptionRequired | The year exists, but your plan does not grant access to it. |
| 404 | financialDataForYearNotFound | There is no financial data for this company for the requested year. |
| 429 | dailyFiscalYearLimitExceeded | The daily allowance of distinct company-and-year combinations is exhausted. |
Financial Metrics
Detailed description of all available financial metrics and their calculations.
Core Metrics
revenue Total Revenue profit Net Profit total_assets Total Assets equity Equity Financial Ratios
roa Return on Assets (%) roe Return on Equity (%) profit_margin Profit Margin (%) operating_margin Operating Margin (%) Errors and Status Codes
HTTP Status Codes
| Status | Description | When it occurs |
|---|---|---|
| 200 | Success | Request completed successfully |
| 400 | Bad Request | Invalid or missing parameters |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | API key does not have access to this resource |
| 404 | Not Found | The requested object does not exist |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Server Error | Internal server error |
Error Format
All errors are returned in the following JSON format:
{
"error": "Описание на грешката"
}