API Documentation — TheCompanyBook

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 — financial reports, contact details, ownership, connected parties and bankruptcy. Free tier up to 300 requests/day.

Key Features

Search companies by UIC, name, district

Search people by name and identifier

Detailed company information

Change history

JSON data format

Fast and reliable API

Unified search

Up-to-date data

Authentication

All API requests require a valid API key. The key is passed 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

Free users: 300 requests per day

Subscribed users: 3,000 requests per day

Limits reset daily at midnight (EET/EEST)

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.

GET /api/companies/:uic

Parameters

uic *

Company UIC (can include "BG" prefix)

with_data

true/false - full or basic data

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}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

// Примери за използване
// Основни данни
const basicData = await getCompany("{uic}");

// Пълни данни (включва история, дъщерни фирми)
const fullData = await getCompany("{uic}", true);

People

API endpoints for working with people

Get Person by Identifier

Retrieve detailed information about a specific person.

GET /api/people/:indent

Parameters

indent *

Identification number (Indent/LNC)

with_data

true/false - full or basic data

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}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

// Основни данни
const basicData = await getPerson("{indent}");

// Пълни данни (включва всички фирми)
const fullData = await getPerson("{indent}", true);

Search People

Search for people by name.

GET /api/people/search

Query Parameters

Parameter

Type

Description

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}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

const people = await searchPeople("Иван Петров");

Unified Search

Search simultaneously in companies and people with one query. Perfect for quick searching.

GET /api/shared/search

Query Parameters

name *

Search text (minimum 3 characters)

limit

Number of results per type (default: 3)

Response

{
  "companies": [
    {
      "uic": "123456789",
      "name": "Example Ltd",
      "legalForm": "ООД",
      "status": "N"
    }
  ],
  "people": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Иван Петров",
      "indent": "1234567890",
      "companies": 3
    }
  ]
}

Code Examples

// Обединено търсене във фирми и лица
async function unifiedSearch(query, limit = 5) {
  const response = await fetch(
    `https://api.companybook.bg/api/shared/search?name=${encodeURIComponent(query)}&limit=${limit}`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

const results = await unifiedSearch("Иван");
console.log("Фирми:", results.companies);
console.log("Лица:", results.people);

Advantages

• One query to search both data types
• Automatic result limitation
• Optimized for user interfaces

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.

GET /api/companies/:uic/financial

Parameters

uic *

Company UIC (can include "BG" prefix)

Access Control

• Subscribed users: Full financial data for all available years

• Non-subscribed users: Limited data (without the last financial year)

Daily Rate Limits

Rate limits for accessing financial data through the API depend on your plan:

• Free users: 30 unique requests per day (30 different UICs)

• Subscribed users: 300 unique requests per day (300 different UICs)

⚠️ Limits reset daily at midnight (EET/EEST)

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`,
    {
      headers: { "X-API-Key": "your_api_key_here" }
    }
  );
  return await response.json();
}

const financialData = await getCompanyFinancial("123456789");

// Достъп до данни за конкретна година
const year2023 = financialData.financial_data["2023"];
console.log("Приходи 2023:", year2023.general_info.revenue);

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

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": "Описание на грешката"
}

Common Errors

400

name query must be at least 3 characters

The search text must be at least 3 characters

400

Invalid limit parameter

The limit parameter must be an integer

404

Company/Person not found

The company or person was not found in the database

429

Rate limit exceeded

Rate limit exceeded. Wait before making another request

Contact Us

Overview

Additional Developer Resources

Key Features

Authentication

Daily Request Limits

Response Format

Data Models

Company

Basic data (with_data=false)

Full data (with_data=true)

Person

Basic data (with_data=false)

Full data (with_data=true)

Unified Search

Data Type Information

Company Status

Legal Forms

District Codes

Companies

Get Company by UIC

Parameters

Response

Code Examples

People

Get Person by Identifier

Parameters

Response

Code Examples

Search People

Query Parameters

Response

Search Examples

Unified Search

Query Parameters

Response

Code Examples

Advantages

Financial Data API

Data Models

FinancialData

YearData

IncomeStatement

BalanceSheet

GeneralInfo

Get Company Financial Data

Parameters

Access Control

Daily Rate Limits

Response Structure

Code Examples

Financial Metrics

Core Metrics

Financial Ratios

Errors and Status Codes

HTTP Status Codes

Error Format

Common Errors