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

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
Clear free and paid access tiers

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

Free account API keys: 100 requests per day
Paid API keys: 3,000 requests per day (Pro); 1,000 requests per day (Pro Lite)
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",                    // 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

District Codes

ID District
1 София (столица)
31 Бургас
32 Варна
45 Пловдив

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

// 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);

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.

GET /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
});

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

// 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);

Search People

Search for people by name. The v2 search endpoint accepts any valid free or paid API key.

GET /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

Parameter
Type
Description
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("Иван Петров");

Unified Search

Search simultaneously in companies and people with one query. The v2 unified endpoint accepts any valid free or paid API key.

GET /api/v2/shared/search

Free and paid API keys can use the v2 unified search endpoint.

Query Parameters

name *
Search text (minimum 3 characters)
limit
Number of results per type (default: 3, max: 500)

Response

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

Code Examples

// Unified search across companies and people
async function unifiedSearch(query, limit = 5) {
  const response = await fetch(
    `https://api.companybook.bg/api/v2/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 {
  // 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.

GET /api/companies/:uic/financial?year=YYYY

Parameters

uic *
Company UIC (can include "BG" prefix)
year *
Fiscal year, exactly four digits (e.g. 2023). Required — a request without it is rejected.

Authentication

Every request requires a valid API key passed in the X-API-Key header.

Access Control

• Subscribed users: Access to every available fiscal year, including the most recent ones
• Non-subscribed users: Access to older fiscal years only; the most recent years return 403 financialSubscriptionRequired
The paid_data_years array lists the fiscal years that require a paid plan.

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:

• Free users: 30 distinct company-and-year combinations per day
• Subscribed users: 300 distinct company-and-year combinations per day on Pro; 100 per day on Pro Lite
• Requesting the same company and the same year again on the same day is free and does not consume the allowance.
• Failed requests, rejected requests and requests that return no data for the year cost nothing.
⚠️ The allowance resets daily at midnight, Europe/Sofia time.

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);

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

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