NEW: Download company documents from TR –
try it now!

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

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

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

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

// Получаване на юридическо лице по ЕИК
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);

Search Companies

Search for companies with various filters.

GET /api/companies/search

Query Parameters

Parameter
Type
Description
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
});

Get Company Documents

Retrieve document data for a company by UIC. Returns financial statements and other documents (AJ and BH types).

GET /api/companies/documents/:uic

Parameters

uic *
Company UIC. Can include "BG" prefix (e.g., "BG123456789")

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.

GET /api/companies/:uic/download

Parameters

uic *
Company UIC. Can include "BG" prefix
id *
Document ID (from documents endpoint)
type *
Document type: financial, statements_aj, statements_bh
year
Document year (required for some types)

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

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

GET /api/people/:indent

Parameters

indent *
Identification number (EGN/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}`
  );
  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}`
  );
  return await response.json();
}

// Пример за използване
const people = await searchPeople("Иван Петров");
console.log(people);

Statistics

GET /api/people/count

Get the total number of people in the registry

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

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.

GET /api/relationships/:identifier

Parameters

identifier *
Company UIC (9 digits) or person EGN
depth
integer (1-5, default: 2) - Traversal depth
type
all/ownership/management - Filter by relationship type
include_historical
boolean - Include historical relationships

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

Relationship Types

Ownership

  • SoleCapitalOwner Sole Capital Owner (100%)
  • Partners Partners/shareholders
  • ActualOwners Beneficial Owners
  • PhysicalPersonTrader Sole Trader

Management

  • Managers Managers
  • Representatives Representatives
  • BoardOfDirectors Board of Directors
  • Procurators Procurators

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

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