# CompanyBook.bg - Full API Reference

> Bulgarian company registry providing comprehensive data on companies and individuals through a public API

CompanyBook.bg is a searchable database of Bulgarian companies and people, sourced from the official Bulgarian Trade Register. Access detailed company information including management, ownership, financial data, addresses, and historical changes.

## API Documentation

- [Full API Documentation](https://companybook.bg/api-docs): Complete interactive reference with code examples

## Architecture

- Base URL: https://api.companybook.bg/api
- Authentication: None required - completely free access
- Response Format: JSON
- Caching: 24-hour cache with 48-hour stale-while-revalidate
- Rate Limiting: 100 requests per minute per IP address

## Companies API

### GET /api/companies/:uic

Get detailed company information by UIC (Unique Identification Code).

**Parameters:**
- `uic` (required): Company UIC, accepts with or without "BG" prefix
- `with_data` (optional): Boolean - returns expanded data when `true`

**Response with with_data=false:**
```json
{
  "uic": "123456789",
  "name": "Example Ltd",
  "legalForm": "ООД",
  "status": "N",
  "transliteration": "Example OOD"
}
```

**Response with with_data=true:**
```json
{
  "company": {
    "id": "...",
    "uic": "123456789",
    "companyName": { "name": "...", "name_tags": [...] },
    "legalForm": "ООД",
    "status": "N",
    "seat": { "country": "...", "region": "...", "address": "..." },
    "contacts": { "email": "...", "phone": "...", "website": "..." },
    "managers": [...],
    "capital": { "amount": "...", "currency": "BGN" },
    "partners": [...],
    "nkids": [...],
    "lastUpdated": "..."
  },
  "history": [...],
  "daughters": [...]
}
```

### GET /api/companies/search

Search companies with multiple filters.

**Query Parameters:**
- `uic` (string): Exact UIC match
- `name` (string): Company name (partial match)
- `district` (number): District ID (1-56, see districts list)
- `status` (boolean): `true` for active, `false` for inactive
- `legal_form` (string): Legal form (see legal forms list)
- `with_data` (boolean): Include full company data
- `limit` (integer): Results per page (default: 20)

**Response:**
```json
{
  "results": [
    {
      "uic": "123456789",
      "name": "Example Ltd",
      "legalForm": "ООД",
      "status": "N",
      "transliteration": "Example OOD"
    }
  ],
  "total": 145,
}
```

### GET /api/companies/documents/:uic

Get document data for a company by UIC. Returns financial statements and other documents (statements_aj, statements_bh).

**Parameters:**
- `uic` (required): Company UIC, can include "BG" prefix (e.g., "BG123456789" or "123456789")

**Authentication:**
- Optional - Returns enhanced data when authenticated
- Session cookie or X-API-Key header with user API key
- Document IDs included only for authenticated users

**Document Filtering:**
- Only returns statements_aj and statements_bh type documents for non-financial documents
- Financial documents: Only shows unprocessed documents from 2022+ if no processed documents exist for that year
- Unprocessed financial documents are displayed shifted by one year (e.g., 2025 documents appear in 2024)
- Only includes G2 applications (documents containing "Г2" or "G2" in the name)

**Response:**
```json
{
  "uic": "123456789",
  "name": "Example Ltd",
  "financial_documents": {
    "2024": [
      {
        "id": "doc123", // Only included for authenticated users
        "name": "Financial Report 2024",
        "date": "2024-12-31",
        "type": "financial",
      }
    ]
  },
  "other_documents": {
    "statements_aj": [
      {
        "id": "doc456", // Only included for authenticated users
        "name": "Registration Statement AJ",
        "date": "2024-01-15",
        "type": "statements_aj"
      }
    ],
    "statements_bh": [
      {
        "id": "doc789", // Only included for authenticated users
        "name": "Change Statement BH",
        "date": "2024-03-20",
        "type": "statements_bh"
      }
    ]
  }
}
```

### GET /api/companies/:uic/download

Download specific documents for a company. Requires authentication and allows only financial,type documents.

**Parameters:**
- `uic` (required): Company UIC, can include "BG" prefix
- `id` (required): Document ID (obtained from the documents endpoint)
- `type` (required): Document type. Allowed values: "financial", "statements_aj", "statements_bh"
- `year` (optional): Document year (required for some document types)

**Authentication:**
- Required - Must be authenticated via session or API key
- Session cookie or Authorization header with Bearer token
- API key authentication via X-API-Key header with user API key
- Rate limiting: 20 downloads per minute per authenticated user

**Document Type Restrictions:**
- Only allows downloading financial, statements_aj, and statements_bh type documents
- Other document types will return a 400 Bad Request error

**Example Requests:**
```bash
# Using session authentication
curl "https://api.companybook.bg/api/companies/123456789/download?id=doc123&type=financial&year=2024" \
  -H "Authorization: Bearer your_session_token"

# Using API key authentication  
curl "https://api.companybook.bg/api/companies/BG123456789/download?id=doc123&type=statements_aj" \
  -H "X-API-Key: your_api_key"
```

**Response:**
- Success: Returns the document file as a download with appropriate Content-Type and Content-Disposition headers
- Error: JSON error response with localized error messages in Bulgarian and English

**Error Responses:**
- 400 - Invalid parameters or unsupported document type
- 401 - Authentication required (no valid session or API key)
- 404 - Document not found
- 429 - Rate limit exceeded (too many downloads)
- 500 - Internal server error

### GET /api/companies/count

Get total number of companies in registry.

**Response:**
```json
{
  "total": 1234567
}
```

## People API

### GET /api/people/:indent

Get person information by identifier (EGN/LNCh).

**Parameters:**
- `indent` (required): Person identifier (EGN or LNCh number)
- `with_data` (optional): Boolean - returns full company list when `true`

**Response with with_data=false:**
```json
{
  "id": "507f1f77bcf86cd799439011",
  "name": "Иван Петров",
  "indent": "1234567890",
  "companies": 3
}
```

**Response with with_data=true:**
```json
{
  "_id": "507f1f77bcf86cd799439011",
  "indent": "1234567890",
  "name": "Иван Петров",
  "personCompanies": [
    {
      "uic": "123456789",
      "company_name": { "name": "Example Ltd" },
      "legalForm": "Едноличен Търговец",
      "share": "20"
      "roles": [
        {
          "position": "Partner",
          "from": "2020-01-01",
        }
      ]
    }
  ],
  "nameTags": ["ivan", "petrov"]
}
```

### GET /api/people/search

Search people by name.

**Query Parameters:**
- `name` (required): Person name (minimum 3 characters)
- `with_data` (boolean): Include full company lists
- `limit` (integer): Results per page (default: 20)

**Response:**
```json
{
  "results": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Иван Петров",
      "indent": "1234567890",
      "companies": 3
    }
  ],
  "total": 42,
}
```

### GET /api/people/count

Get total number of people in registry.

**Response:**
```json
{
  "total": 987654
}
```

## Unified Search API

### GET /api/shared/search

Search both companies and people simultaneously.

**Query Parameters:**
- `name` (required): Search query (minimum 3 characters)
- `limit` (integer): Results per type (default: 3)

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

## Relationships API

### GET /api/relationships/:identifier

Get network graph of ownership and management relationships for companies or people. Supports multi-level traversal to discover connected entities.

**Parameters:**
- `identifier` (required): Company UIC or person identifier (EGN/LNCh)
- `depth` (optional): Traversal depth levels (default: 3, max: 5)
- `type` (optional): Relationship filter - "all", "ownership", or "management" (default: "all")
- `include_historical` (optional): Boolean - include historical relationships (default: false)

**Response:**
```json
{
  "root": {
    "id": "123456789",
    "type": "company",
    "name": "Example OOD"
  },
  "relationships": [
    {
      "entity": {
        "id": "987654321",
        "name": "Owner Company",
        "type": "company"
      },
      "relationshipType": "Partners",
      "depth": 1,
      "metadata": {
        "share": "60.00%"
      },
      "isActive": true,
      "direction": "owned_by"
    }
  ],
  "graph": {
    "nodes": [
      {"id": "123456789", "label": "Example OOD", "type": "company"},
      {"id": "987654321", "label": "Owner Company", "type": "company"}
    ],
    "edges": [
      {"from": "123456789", "to": "987654321", "type": "Partners", "label": "60%"}
    ]
  },
  "totalEntities": 15
}
```

**Relationship Types:**

*Ownership:*
- SoleCapitalOwner - Single owner of EOOD
- Partners - Company partners/shareholders
- ActualOwners - Beneficial owners
- PhysicalPersonTrader - Sole trader owner

*Management:*
- Managers - Company managers
- Representatives - Legal representatives
- BoardOfDirectors - Board members
- Procurators - Authorized signatories

**Performance Notes:**
- Maximum depth: 5 levels
- Request timeout: 30 seconds for complex graphs
- Results are cached for 24 hours
- Automatic cycle detection prevents infinite loops
- Batch loading optimizes database queries

## Data Models

### Company Data Structure

**Core Fields:**
- `uic`: Unique Identification Code
- `companyName`: Name object with tags
- `legalForm`: Legal entity type
- `status`: "N" (active) or other status codes
- `insolvencyDate`: If applicable
- `suspendProceedings`: Suspension information

**Location:**
- `seat`: Primary address (country, region, district, municipality, settlement, address, postCode)
- `correspondenceSeat`: Mailing address

**Contact:**
- `contacts`: Email, phone, fax, website

**Business:**
- `subjectOfActivity`: Business description
- `nkids`: Array of NKID economic activity codes

**Management:**
- `managers`: Array of managing persons
- `representatives`: Legal representatives (types 101, 102, 103)
- `boardOfDirectors`: Board members
- `supervisingBoard`: Supervisory board
- `procurators`: Authorized signatories
- `liquidators`: Liquidation managers
- `trustees`: Insolvency trustees

**Financial:**
- `capital`: Amount, currency, paid amount, non-monetary part
- `shares`: Type, count, nominal value, special rights
- `depositedFunds`: Deposited funds (EUR/BGN)
- `nonMonetaryDeposits`: Non-monetary contributions

**Ownership:**
- `partners`: Partners with liability and contribution info
- `soleCapitalOwner`: Single owner (for EOOD)
- `actualOwner`: Beneficial owners
- `physicalPersonTrader`: For sole traders
- `unlimitedLiabilityPartners`: General partners

**Special Info:**
- `insolvencyInfo`: Status, date, court, case number, trustees
- `liquidationInfo`: Status, dates, liquidators
- `registerInfo`: VAT registration details

**Metadata:**
- `lastUpdated`: Last modification timestamp
- `history`: Array of historical changes

### Person Data Structure

- `_id`: MongoDB ObjectId
- `indent`: EGN or LNCh number
- `name`: Full name
- `personCompanies`: Array of affiliated companies with roles
- `nameTags`: Search tags

### Role Types

Common positions: Управител (Manager), Съдружник (Partner), Член на СД (Board Member), Представител (Representative), Едноличен собственик (Sole Owner), Прокурист (Attorney), Ликвидатор (Liquidator), Синдик (Trustee)

## Reference Data

### Districts (28 total)

- 1: София (столица) / Sofia (capital)
- 30: Благоевград / Blagoevgrad
- 31: Бургас / Burgas
- 32: Варна / Varna
- 33: Велико Търново / Veliko Tarnovo
- 34: Видин / Vidin
- 35: Враца / Vratsa
- 36: Габрово / Gabrovo
- 37: Добрич / Dobrich
- 38: Кърджали / Kardzhali
- 39: Кюстендил / Kyustendil
- 40: Ловеч / Lovech
- 41: Монтана / Montana
- 42: Пазарджик / Pazardzhik
- 43: Перник / Pernik
- 44: Плевен / Pleven
- 45: Пловдив / Plovdiv
- 46: Разград / Razgrad
- 47: Русе / Ruse
- 48: Силистра / Silistra
- 49: Сливен / Sliven
- 50: Смолян / Smolyan
- 51: София / Sofia (region)
- 52: Стара Загора / Stara Zagora
- 53: Търговище / Targovishte
- 54: Хасково / Haskovo
- 55: Шумен / Shumen
- 56: Ямбол / Yambol

### Legal Forms (18 total)

- Еднолично дружество с ограничена отговорност (EOOD) - Single-member LLC
- Едноличен търговец (ET) - Sole trader
- Дружество с ограничена отговорност (OOD) - LLC
- Сдружение - Association
- Акционерно дружество (AD) - Joint-stock company
- Събирателно дружество - General partnership
- Фондация - Foundation
- Кооперация - Cooperative
- Народно читалище - Community center
- Еднолично акционерно дружество (EAD) - Single-member JSC
- Клон на чуждестранен търговец - Foreign trader branch
- Командитно дружество - Limited partnership
- Държавно предприятие - State enterprise

### NKID Codes

Bulgarian economic activity classification codes (NKID) available via separate JSON import. Codes follow EU NACE classification.

## Code Examples

### JavaScript/TypeScript

```javascript
// Get company with full data
const response = await fetch(
  'https://api.companybook.bg/api/companies/123456789?with_data=true'
);
const data = await response.json();

// Search companies
const searchResponse = await fetch(
  'https://api.companybook.bg/api/companies/search?name=Example&district=1&status=true'
);
const results = await searchResponse.json();

// Get company documents
const documentsResponse = await fetch(
  'https://api.companybook.bg/api/companies/documents/123456789',
  {
    headers: {
      'X-API-Key': 'your_api_key' // Optional for enhanced data
    }
  }
);
const documents = await documentsResponse.json();

// Download company document (requires authentication)
const downloadResponse = await fetch(
  'https://api.companybook.bg/api/companies/123456789/download?id=doc123&type=financial&year=2024',
  {
    headers: {
      'X-API-Key': 'your_api_key'
    }
  }
);
const blob = await downloadResponse.blob();

// Unified search
const unifiedResponse = await fetch(
  'https://api.companybook.bg/api/shared/search?name=Example&limit=5'
);
const unified = await unifiedResponse.json();
```

### Python

```python
import requests

# Get company with full data
response = requests.get(
    'https://api.companybook.bg/api/companies/123456789',
    params={'with_data': 'true'}
)
data = response.json()

# Search companies
search_response = requests.get(
    'https://api.companybook.bg/api/companies/search',
    params={'name': 'Example', 'district': 1, 'status': True}
)
results = search_response.json()

# Get company documents
documents_response = requests.get(
    'https://api.companybook.bg/api/companies/documents/123456789',
    headers={'X-API-Key': 'your_api_key'}  # Optional for enhanced data
)
documents = documents_response.json()

# Download company document (requires authentication)
download_response = requests.get(
    'https://api.companybook.bg/api/companies/123456789/download',
    params={'id': 'doc123', 'type': 'financial', 'year': '2024'},
    headers={'X-API-Key': 'your_api_key'}
)
if download_response.headers.get('content-type') != 'application/json':
    # Save file
    with open('document.pdf', 'wb') as f:
        f.write(download_response.content)

# Unified search
unified_response = requests.get(
    'https://api.companybook.bg/api/shared/search',
    params={'name': 'Example', 'limit': 5}
)
unified = unified_response.json()
```

### cURL

```bash
# Get company with full data
curl "https://api.companybook.bg/api/companies/123456789?with_data=true"

# Search companies
curl "https://api.companybook.bg/api/companies/search?name=Example&district=1&status=true"

# Get company documents (optional authentication for enhanced data)
curl "https://api.companybook.bg/api/companies/documents/123456789" \
  -H "X-API-Key: your_api_key"

# Download company document (requires authentication)
curl "https://api.companybook.bg/api/companies/123456789/download?id=doc123&type=financial&year=2024" \
  -H "X-API-Key: your_api_key" \
  -o document.pdf

# Unified search
curl "https://api.companybook.bg/api/shared/search?name=Example&limit=5"
```

## Website Routes

- `/`: Homepage with search
- `/companies/:uic`: Company detail pages
- `/people/:indent`: Person detail pages
- `/api-docs`: Full interactive API documentation
- `/search`: Search interface
- `/sitemap-index.xml`: Sitemap index with all companies and people

## Technical Stack

- Framework: Astro v5 with React integration
- Deployment: Cloudflare with SSR enabled
- Styling: TailwindCSS v4
- Cache Strategy: 24-hour cache with 48-hour stale-while-revalidate, 7-day stale-if-error

## Use Cases

- Business intelligence and market research
- Due diligence and background checks
- Competitive analysis
- Lead generation and prospecting
- Compliance and regulatory reporting
- Academic research on Bulgarian economy
- Integration with CRM and business tools