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
Rate Limits
Our API is free to use, but we apply a limit of 100 requests per minute per IP address to ensure service stability for all users. If you exceed the limit, you will receive HTTP status code 429.
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": "1234567890", // ЕГН/ЛНЧ
"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
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": "Описание на грешката"
}