Overview
RESTful API for the Bulgarian Commercial Register
Additional Developer Resources
Swagger Documentation: Interactive API documentation with live testing is available at api.companybook.bg/docs
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.
RESTful API for accessing data from the Bulgarian Commercial Register. Search, extract and integrate company and individual data with ease and reliability.
Key Features
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", // ЕИК на юридическо лицета
"name": "Example Ltd", // Наименование
"legalForm": "ООД", // Правна форма
"status": "N", // Статус (N=активна, L=ликвидирана)
"transliteration": "Example OOD" // Транслитерация
} Full data (with_data=true)
{
"company": {
// Основна информация
"id": "507f1f77bcf86cd799439011",
"uic": "123456789",
"companyName": {
"name": "Example Ltd",
"name_tags": ["exa", "xam"]
},
"companyNameTransliteration": {
"name": "Example OOD"
"name_tags": ["exa", "xam]
},
"legalForm": "Дружество с ограничена отговорност",
"status": "N",
// Адреси
"seat": {
"country": "България",
"region": "София",
"district": "София (столица)",
"municipality": "София",
"settlement": "София",
"area": "Център",
"street": "ул. Витоша",
"streetNumber": "15",
"block": "2",
"entrance": "А",
"floor": "3",
"apartment": "5",
"postCode": "1000",
"districtid": 1
},
"correspondenceSeat": { /* същата структура */ },
// Контакти
"contacts": {
"email": "[email protected]",
"phone": "+359 2 123 4567",
"fax": "+359 2 123 4568",
"website": "https://example.com"
},
// Дейност
"subjectOfActivity": "Консултантски услуги",
"nkids": [
{
"code": "62.02",
"description": "Дейности в областта на информационните технологии",
"id": "nkid123"
}
],
// Мениджмънт
"managers": [
{
"name": "Иван Петров",
"indent": "1234567890",
"address": "София, ул. Витоша 1"
}
],
"representatives": [ /* същата структура */ ],
"boardOfDirectors": [ /* същата структура */ ],
// Финансова информация
"capital": {
"amount": "2000",
"currency": "BGN",
"paidAmount": "2000"
},
// Собственост
"partners": [
{
"person": {
"name": "Иван Петров",
"indent": "1234567890",
"address": "София"
},
"liabilityType": "ограничена",
"contribution": "1000 BGN"
}
],
// ДДС регистрация
"registerInfo": {
"name": "Example Ltd",
"vat": "BG123456789",
"address": "София, ул. Витоша 1",
"registrationDate": "2020-01-15"
},
// Метаданни
"lastUpdated": "2024-01-15T10:30:00Z"
},
// История на промените
"history": [
{
"deedUIC": "123456789",
"timestamp": "2024-01-15T10:30:00Z",
"changeType": "address_change",
"field": "seat.address",
"oldValue": "ул. Стара 5",
"newValue": "ул. Витоша 1"
}
],
// Дъщерни фирми
"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", // Уникален идентификатор
"name": "Иван Петров", // Име на лицето
"indent": "aaaaxxxxxxxxxxxxxxxx", // Indent/
"companies": 3 // Брой свързани фирми
} Full data (with_data=true)
{
"_id": "507f1f77bcf86cd799439011",
"indent": "1234567890",
"name": "Иван Петров",
"nameTags": ["иван", "петров", "ivan", "petrov"],
// Всички фирми, в които участва лицето
"personCompanies": [
{
"uic": "123456789",
"legalForm": "Дружество с ограничена отговорност",
"share": "50.00", // Дял в компанията (ако е съдружник)
"company_name": {
"name": "Example Ltd",
"name_tags": ["example", "ltd"]
},
"roles": [
{
"position": "Manager", // Длъжност/роля
"from": "2020-01-15", // От дата
"until": null, // До дата (null = активен)
},
{
"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", // Неактивна роля
"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
// Получаване на юридическо лице по ЕИК
async function getCompany(uic, withData = false) {
const response = await fetch(
`https://api.companybook.bg/api/companies/${uic}?with_data=${withData}`
);
return await response.json();
}
// Примери за използване
// Основни данни
const basicData = await getCompany("{uic}");
// Пълни данни (включва история, дъщерни фирми)
const fullData = await getCompany("{uic}", true); import requests
# Получаване на юридическо лице по ЕИК
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()}
)
return response.json()
# Примери за използване
# Основни данни
basic_data = get_company("{uic}")
# Пълни данни (включва история, дъщерни фирми)
full_data = get_company("{uic}", True) # Получаване на юридическо лице с основни данни
curl "https://api.companybook.bg/api/companies/{uic}"
# Получаване на юридическо лице с пълни данни (история, дъщерни фирми)
curl "https://api.companybook.bg/api/companies/{uic}?with_data=true" Search Companies
Search for companies with various filters.
/api/companies/search Query Parameters
uic string Exact UIC name string Company name district number District ID status boolean Active/inactive legal_form string Legal form with_data boolean Full data limit integer Number of results Response
{
"results": [
{
"uic": "123456789",
"name": "Example Ltd",
"legalForm": "ООД",
"status": "N"
}
],
"total": 145
} Search Examples
// Търсене на фирми
async function searchCompanies(params) {
const queryString = new URLSearchParams(params).toString();
const response = await fetch(
`https://api.companybook.bg/api/companies/search?${queryString}`
);
return await response.json();
}
// Примери за търсене
// Основни резултати
const activeCompanies = await searchCompanies({
name: "Example",
status: true,
limit: 20
});
// Пълни данни с with_data
const companiesWithData = await searchCompanies({
district: 1, // София (столица)
legal_form: "ООД",
with_data: true
}); # Търсене на фирми
def search_companies(**params):
response = requests.get(
"https://api.companybook.bg/api/companies/search",
params=params
)
return response.json()
# Примери за търсене
# Основни резултати
active_companies = search_companies(
name="Example",
status=True,
limit=20
)
# Пълни данни с with_data
companies_with_data = search_companies(
district=1, # София (столица)
legal_form="ООД",
with_data=True
) # Търсене по име и статус curl "https://api.companybook.bg/api/companies/search?name=Example&status=true" # Търсене с пълни данни по област (ID) curl "https://api.companybook.bg/api/companies/search?district=1&legal_form=ООД&with_data=true"
Get Company Documents
Retrieve document data for a company by UIC. Returns financial statements and other documents (AJ and BH types).
/api/companies/documents/:uic Parameters
Authentication
• Optional - Enhanced data when authenticated
• Session cookie or X-API-Key header
• Document IDs included only for authenticated users
Response
{
"uic": "123456789",
"name": "Example Ltd",
"financial_documents": {
"2024": [
{
"id": "doc123", // Only for authenticated
"name": "Financial Report 2024",
"date": "2024-12-31",
"type": "financial",
}
]
},
"other_documents": {
"statements_aj": [...],
"statements_bh": [...]
}
} Download Company Document
Download specific documents for a company. Requires authentication and allows only financial, AJ, or BH type documents.
/api/companies/:uic/download Parameters
Authentication
• X-API-Key header
• Rate limit: 20 downloads per minute
Example Request
# Using session authentication
curl "https://api.companybook.bg/api/companies/123456789/download?id=doc123&type=financial&year=2024" \
-H "Authorization: Bearer session_token"
# Using API key authentication
curl "https://api.companybook.bg/api/companies/BG123456789/download?id=doc123&type=aj" \
-H "X-API-Key: your_api_key" Response
• Success: File download with appropriate headers
• Error: JSON with localized error messages
Error Responses
- • 400 - Invalid parameters or unsupported document type
- • 401 - Authentication required
- • 404 - Document not found
- • 429 - Rate limit exceeded
- • 500 - Internal server error
Statistics
/api/companies/count Get the total number of companies in the registry
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
// Получаване на лице по идентификатор
async function getPerson(indent, withData = false) {
const response = await fetch(
`https://api.companybook.bg/api/people/${indent}?with_data=${withData}`
);
return await response.json();
}
// Примери за използване
// Основни данни
const basicData = await getPerson("{indent}");
// Пълни данни (включва всички фирми)
const fullData = await getPerson("{indent}", true); # Получаване на лице по идентификатор
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()}
)
return response.json()
# Примери за използване
# Основни данни
basic_data = get_person("{indent}")
# Пълни данни (включва всички фирми)
full_data = get_person("{indent}", True) # Получаване на лице с основни данни
curl "https://api.companybook.bg/api/people/{indent}"
# Получаване на лице с пълни данни (всички фирми)
curl "https://api.companybook.bg/api/people/{indent}?with_data=true" Search People
Search for people by name.
/api/people/search Query Parameters
name * string Person name with_data boolean Full data limit integer Number of results Response
{
"results": [
{
"id": "507f1f77bcf86cd799439011",
"name": "Иван Петров",
"indent": "1234567890",
"companies": 3
}
],
"total": 42
} Search Examples
// Търсене на лица
async function searchPeople(name, limit = 20) {
const response = await fetch(
`https://api.companybook.bg/api/people/search?name=${encodeURIComponent(name)}&limit=${limit}`
);
return await response.json();
}
// Пример за използване
const people = await searchPeople("Иван Петров");
console.log(people); # Търсене на лица
def search_people(name, limit=20):
response = requests.get(
"https://api.companybook.bg/api/people/search",
params={"name": name, "limit": limit}
)
return response.json()
# Пример за използване
people = search_people("Иван Петров")
print(people) # Търсене на лица по име curl "https://api.companybook.bg/api/people/search?name=Иван" # Търсене с лимит curl "https://api.companybook.bg/api/people/search?name=Петров&limit=30"
Statistics
/api/people/count Get the total number of people in the registry
Bankruptcy API
Endpoints for bankruptcy announcements, syndics, and courts
Data Models
TypeScript interfaces for API responses.
Announcement
interface Announcement {
id: string;
debtor_name: string;
debtor_eik: string;
case_number: string;
case_year: number;
court_name: string;
offering_date?: Date;
offer_deadline?: Date;
status: string;
is_closed: boolean;
publish_date: Date;
syndic: Syndic;
second_syndic?: Syndic;
objects: AnnouncementObject[];
parsed_objects?: ParsedObject[];
} Syndic
interface Syndic {
id: string;
full_name: string;
full_address: string;
phone?: string;
email?: string;
syndic_specialty?: string;
order_date?: string;
order_number?: string;
} AnnouncementObject
interface AnnouncementObject {
id: string;
object_type: string;
object_kind: string;
condition?: string;
notes?: string;
value?: string;
address?: Address;
} PaginatedResponse
interface PaginatedResponse<T> {
data: T[];
current_page: number;
page_size: number;
total_pages: number;
total_count: number;
has_next: boolean;
has_prev: boolean;
} Get Announcement by ID
Retrieve detailed information about a specific announcement by its unique identifier.
/api/announcements/:id Parameters
Access Control
Response
{
"id": "1234567890",
"debtor_name": "Example Company",
"debtor_eik": "123456789",
"case_number": "1/2024",
"case_year": 2024,
"court_name": "Sofia City Court",
"status": "active",
"is_closed": false,
"publish_date": "2024-01-15",
"syndic": {
"full_name": "John Doe",
"full_address": "Sofia, Bulgaria"
},
"objects": [...]
} Code Examples
// Получаване на търг по ID
async function getAnnouncement(id) {
const response = await fetch(
`https://api.companybook.bg/api/announcements/${id}`
);
return await response.json();
}
// Пример за използване
const announcement = await getAnnouncement("1234567890");
console.log("Търг:", announcement.debtor_name); import requests
# Получаване на търг по ID
def get_announcement(id):
response = requests.get(
f"https://api.companybook.bg/api/announcements/{id}"
)
return response.json()
# Пример за използване
announcement = get_announcement("1234567890")
print("Търг:", announcement["debtor_name"]) # Получаване на търг по ID curl -X GET "https://api.companybook.bg/api/announcements/1234567890" \ -H "Accept: application/json" \ -H "User-Agent: MyApp/1.0" # За абонирани потребители (пълни данни) curl -X GET "https://api.companybook.bg/api/announcements/1234567890" \ -H "Accept: application/json" \ -H "X-API-Key: your_api_key_here"
Search Announcements
Search bankruptcy announcements with various filters for debtor, court, date, and status.
/api/announcements Query Parameters
debtor_name string Debtor name debtor_eik string Debtor EIK court_name string Court name is_closed boolean Closed status publish_date_from date Date from page integer Page (default 1) page_size integer Results per page (max 100) Response
{
"data": [
{
"id": "1234567890",
"debtor_name": "Example Company",
"debtor_eik": "123456789",
"status": "active",
"is_closed": false,
"publish_date": "2024-01-15"
}
],
"current_page": 1,
"page_size": 50,
"total_pages": 10,
"total_count": 500,
"has_next": true,
"has_prev": false
} Search Examples
// Търсене на търгове
async function searchAnnouncements(params) {
const queryString = new URLSearchParams(params).toString();
const response = await fetch(
`https://api.companybook.bg/api/announcements?${queryString}`
);
return await response.json();
}
// Примери за търсене
const activeAnnouncements = await searchAnnouncements({
is_closed: false,
page: 1,
page_size: 50
});
// Търсене по дата
const recentAnnouncements = await searchAnnouncements({
publish_date_from: "2024-01-01",
publish_date_to: "2024-12-31"
}); import requests
# Търсене на търгове
def search_announcements(**params):
response = requests.get(
"https://api.companybook.bg/api/announcements",
params=params
)
return response.json()
# Примери за търсене
active_announcements = search_announcements(
is_closed=False,
page=1,
page_size=50
)
# Търсене по дата
recent_announcements = search_announcements(
publish_date_from="2024-01-01",
publish_date_to="2024-12-31"
) # Търсене на активни търгове curl -X GET "https://api.companybook.bg/api/announcements?is_closed=false&page=1&page_size=50" \ -H "Accept: application/json" \ -H "User-Agent: MyApp/1.0" # Търсене по дата и компания curl -X GET "https://api.companybook.bg/api/announcements?publish_date_from=2024-01-01&publish_date_to=2024-12-31&debtor_name=Example" \ -H "Accept: application/json" # Комплексно търсене с множество филтри curl -X GET "https://api.companybook.bg/api/announcements?debtor_eik=123456789&court_name=София&is_closed=false" \ -H "Accept: application/json" \ -H "X-API-Key: your_api_key_here"
Get Syndics List
Get paginated list of bankruptcy syndics.
/api/syndics Query Parameters
page integer Page (default 1) page_size integer Results per page (max 100) Response
{
"data": [
{
"id": "syndic123",
"full_name": "John Doe",
"full_address": "Sofia, Bulgaria",
"phone": "+359888123456",
"email": "[email protected]",
"syndic_specialty": "Commercial Law"
}
],
"current_page": 1,
"page_size": 50,
"total_pages": 5,
"total_count": 250,
"has_next": true,
"has_prev": false
} Search Syndics by Name
Search for syndics by name or partial name match.
/api/syndics/search Query Parameters
name string Syndic name (partial match) page integer Page number page_size integer Results per page Response
{
"data": [
{
"id": "syndic123",
"full_name": "John Doe",
"full_address": "Sofia, Bulgaria",
"announcements_count": 15
}
],
"current_page": 1,
"page_size": 20,
"total_count": 5
} Get Announcements by Syndic
Retrieve all announcements associated with a specific syndic.
/api/syndics/:id/announcements Parameters
Query Parameters
page - Page number page_size - Results per page is_closed - Filter by status Response
{
"data": [
{
"id": "1234567890",
"debtor_name": "Example Company",
"debtor_eik": "123456789",
"case_number": "1/2024",
"status": "active",
"is_closed": false,
"publish_date": "2024-01-15"
}
],
"current_page": 1,
"page_size": 50,
"total_count": 15
} Search Announcement Objects by Type
Search bankruptcy announcement objects by type, location and other criteria. Returns objects with detailed information and related announcement data.
/api/announcements/objects/search Query Parameters
object_kind string Object type (required) city string City (partial match) region string Region min_price_bgn number Minimum price (BGN) max_price_bgn number Maximum price (BGN) is_active boolean Active auction page integer Page number page_size integer Results per page (max 50) Access Control
Response
{
"objects": [
{
"object": {
"id": "obj123",
"object_type": "недвижим имот",
"object_kind": "апартамент",
"condition": "добро състояние",
"value": "150000",
"address": {
"city": "София",
"region": "София",
"full_address": "ул. Примерна 123"
}
},
"parsedObject": {
"price_bgn": 150000.0
},
"announcementId": "1234567890",
"announcementTitle": "Example Company",
"offeringDate": "2024-02-01",
"offerDeadline": "2024-02-15",
"status": "active",
"syndic": {
"full_name": "John Doe",
"phone": "+359888123456"
}
}
],
"pagination": {
"current_page": 1,
"page_size": 20,
"total_count": 150
},
"aggregation": {
"total_objects": 150,
"avg_price_bgn": 175000.0,
"price_range": {
"min": 50000.0,
"max": 500000.0
}
}
} Get Courts List
Get list of all courts that handle bankruptcy cases.
/api/courts Query Parameters
city string Filter by city page integer Page number page_size integer Results per page Response
{
"data": [
{
"id": "court1",
"name": "Софийски градски съд",
"city": "София",
"address": "ул. Съдебна 2",
"phone": "+35929524200",
"active_cases_count": 150
},
{
"id": "court2",
"name": "Окръжен съд - Пловдив",
"city": "Пловдив",
"address": "бул. Шести септември 45",
"active_cases_count": 87
}
],
"current_page": 1,
"page_size": 20,
"total_count": 28
} Financial Data API
Endpoints for retrieving company financial information
Data Models
TypeScript interfaces for financial data structures.
FinancialData
interface FinancialData {
id?: string;
uic: string;
financial_data: Record<string, YearData>;
last_updated: string;
has_2024_data?: boolean;
} 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: number;
financial_institutions_debt: number;
trade_payables: number;
other: number;
};
} GeneralInfo
interface GeneralInfo {
// Core metrics
revenue: number;
profit: number;
accounting_profit: number;
tax: number;
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
roa: number; // Return on Assets (%)
profit_margin: number; // Net Profit Margin (%)
operating_margin: number; // Operating Margin (%)
roe: number; // Return on Equity (%)
current_ratio: number; // Liquidity Ratio
equity_ratio: number; // Financial Autonomy (%)
EBITDA: number; // Earnings Before Interest, Taxes, Depreciation, and Amortization
} Get Company Financial Data
Retrieve comprehensive financial information for a company by UIC including income statements, balance sheets, and key financial ratios.
/api/companies/:uic/financial Parameters
Access Control
Response Structure
{
"uic": "123456789",
"last_updated": "2024-01-15",
"financial_data": {
"2023": {
"income_statement": { ... },
"balance_sheet": { ... },
"general_info": {
"revenue": 1000000.0,
"profit": 135000.0,
"roa": 15.7,
"profit_margin": 13.5,
"roe": 22.5,
// ... други показатели
}
}
},
"has_2024_data": true
} Code Examples
// Получаване на финансови данни на компания
async function getCompanyFinancial(uic) {
const response = await fetch(
`https://api.companybook.bg/api/companies/${uic}/financial`
);
return await response.json();
}
// Пример за използване
const financialData = await getCompanyFinancial("123456789");
// Достъп до данни за конкретна година
const year2023 = financialData.financial_data["2023"];
console.log("Приходи 2023:", year2023.general_info.revenue); import requests
# Получаване на финансови данни на компания
def get_company_financial(uic):
response = requests.get(
f"https://api.companybook.bg/api/companies/{uic}/financial"
)
return response.json()
# Пример за използване
financial_data = get_company_financial("123456789")
# Достъп до данни за конкретна година
year_2023 = financial_data["financial_data"]["2023"]
print("Приходи 2023:", year_2023["general_info"]["revenue"]) # Получаване на финансови данни за компания curl -X GET "https://api.companybook.bg/api/companies/123456789/financial" \ -H "Accept: application/json" \ -H "User-Agent: MyApp/1.0" # С BG префикс curl -X GET "https://api.companybook.bg/api/companies/BG123456789/financial" \ -H "Accept: application/json" # За абонирани потребители (с API ключ) curl -X GET "https://api.companybook.bg/api/companies/123456789/financial" \ -H "Accept: application/json" \ -H "X-API-Key: your_api_key_here"
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 (%) current_ratio Current Ratio Relationship Network
Track ownership and management between companies and people
Get Relationship Network
Powerful endpoint for visualizing corporate structures, ownership chains, and management hierarchies. Uses breadth-first traversal to discover complex business networks.
/api/relationships/:identifier Parameters
Response Structure
{
"root": {
"id": "123456789",
"type": "company",
"name": "Example OOD"
},
"relationships": [
{
"entity": { "id", "name", "type" },
"relationshipType": "Partners",
"depth": 1,
"metadata": {
"share": "60.00%"
},
"isActive": true,
"direction": "owned_by"
}
],
"graph": {
"nodes": [...],
"edges": [...]
},
"totalEntities": 15
} Code Examples
// Получаване на мрежа от връзки за юридическо лице
async function getRelationships(identifier, depth = 3, type = 'all') {
const response = await fetch(
`https://api.companybook.bg/api/relationships/${identifier}?depth=${depth}&type=${type}`
);
return await response.json();
}
// Примери за използване
// Пълна мрежа (собственост + управление) на 3 нива
const fullNetwork = await getRelationships("123456789", 3, "all");
// Само собственост на 4 нива
const ownershipOnly = await getRelationships("123456789", 4, "ownership");
// Само управление
const managementOnly = await getRelationships("1234567890", 2, "management"); import requests
# Получаване на мрежа от връзки
def get_relationships(identifier, depth=3, type='all'):
response = requests.get(
f"https://api.companybook.bg/api/relationships/{identifier}",
params={"depth": depth, "type": type}
)
return response.json()
# Примери за използване
# Пълна мрежа (собственост + управление) на 3 нива
full_network = get_relationships("123456789", 3, "all")
# Само собственост на 4 нива
ownership_only = get_relationships("123456789", 4, "ownership")
# Само управление
management_only = get_relationships("1234567890", 2, "management") # Пълна мрежа от връзки на 3 нива curl "https://api.companybook.bg/api/relationships/123456789?depth=3&type=all" # Само собственост на 4 нива curl "https://api.companybook.bg/api/relationships/123456789?depth=4&type=ownership" # Включване на исторически връзки curl "https://api.companybook.bg/api/relationships/123456789?depth=2&include_historical=true"
Relationship Types
Ownership
- •
SoleCapitalOwnerSole Capital Owner (100%) - •
PartnersPartners/shareholders - •
ActualOwnersBeneficial Owners - •
PhysicalPersonTraderSole Trader
Management
- •
ManagersManagers - •
RepresentativesRepresentatives - •
BoardOfDirectorsBoard of Directors - •
ProcuratorsProcurators
Performance and Limits
- • Maximum depth: 5 levels (to prevent excessive requests)
- • Timeout: Requests timeout after 10 seconds
- • Caching: Results are cached for 5 minutes
- • Cycle detection: API automatically prevents infinite loops
- • Batch loading: Entities at each level are loaded in batches for optimal performance
Errors and Status Codes
HTTP Status Codes
| Status | Description | When it occurs |
|---|---|---|
| 200 | Success | Request completed successfully |
| 400 | Bad Request | Invalid or missing parameters |
| 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": "Описание на грешката"
}