Home › Library › Service Providers

Service Providers

Reference of utility service providers (energy, water, gas companies)

What is a Service Provider?

Service Provider is an enterprise with full legal details registered in the official database of legal entities of the country where it operates.

Country-Specific Details

Ukraine

  • Legal Identifier: EDRPOU (ЄДРПОУ) - 8-digit unique identifier from Unified State Register of Enterprises and Organizations
  • Official Register: Unified State Register of Enterprises and Organizations of Ukraine
  • Bank Identifier: MFO (МФО) - 6-digit bank code

Examples

  • Energy companies (electricity, gas)
  • Water supply companies
  • Internet service providers
  • Management companies (HOA, OSBB)
  • Other utility service providers

Database Limitations

Unfortunately, the database of service providers may be incomplete. Not all companies from the Ukrainian register may be present in the system.

Solution: If you cannot find the service provider you need in the database, you can create a custom contragent with all necessary details.

Custom Contragents

Custom Contragents are user-created entries for companies that are not in the official service providers database. You can manually enter all necessary information.

Available Fields

Required

  • Name - Company full name (minimum 3 characters)

Optional

  • Short Name - Abbreviated name
  • Legal Form - TOV, FOP, PrAT, etc.
  • Tax Number - IPN/EDRPOU (8-12 digits)
  • VAT Number
  • Tax System - General, Simplified, etc.
  • IBAN - International bank account number
  • Bank Name
  • Bank MFO - Bank code (6 digits)
  • SWIFT Code - International bank code (8 or 11 characters)
  • Email
  • Phone
  • Website
  • Director Name
  • Contact Person
  • Registration Date
  • Legal Address
  • Actual Address
  • Notes

Validation Rules

  • Name: Name must be at least 3 characters long
  • Tax Number: Invalid tax number format (must be 8-12 digits)
  • IBAN: Invalid IBAN format
  • Bank MFO: Invalid bank code format (must be 6 digits)
  • SWIFT Code: Invalid SWIFT code format
  • Email: Invalid email format
  • Phone: Invalid phone format (7-20 characters: digits, spaces, +, -, (, ))
  • Website: Invalid URL format (must start with http:// or https://)
  • Registration Date: Registration date cannot be in the future

User Access

You can manage your custom contragents on the dedicated page:

Contragents

REST API

Service Providers API (Read Only)

Service providers from the official database are available via read-only API endpoints:

API Endpoints

GET /api/v1/service-providers              # List all active providers
GET /api/v1/service-providers/{id}         # Get specific provider details

Query Parameters

  • page (integer, optional) - Page number, starts from 1. Default: 1
  • limit (integer, optional) - Items per page, max 100. Default: 50
  • search (string, optional) - Search by company name or EDRPOU code
  • region (string, optional) - Filter by region (exact match)

Request Examples

Example 1: Get first 50 active providers

Use case: Initial load of service providers list

GET /api/v1/service-providers

Example 2: Search by company name

Use case: User types company name in search field. Returns providers matching the search query in name or short_name.

GET /api/v1/service-providers?search=Kyiv Energy Company

Example 3: Search by EDRPOU code

Use case: User enters 8-digit EDRPOU code from utility bill. Returns exact match if provider exists in database.

GET /api/v1/service-providers?search=00131305

Example 4: Filter by region with pagination

Use case: Show providers only from specific region, 20 per page. Useful for filtering local utility companies.

GET /api/v1/service-providers?region=Kyiv&page=1&limit=20

Example 5: Get specific provider details

Use case: User clicks on provider from list to see full details. Returns complete information including timestamps.

GET /api/v1/service-providers/1

List Response Example

{
  "items": [
    {
      "id": 1,
      "edrpou": "00131305",
      "name": "Public Joint Stock Company Kyiv Energy",
      "short_name": "Kyiv Energy JSC",
      "legal_address": "Kyiv, Sakharov St, 139",
      "region": "Kyiv",
      "website": "https://kyivenergo.ua",
      "description": "Electricity distribution company serving Kyiv",
      "phone": "+380 44 467 0067",
      "email": "[email protected]",
      "is_active": true,
      "country": {
        "id": 1,
        "code": "UA",
        "name": {
          "uk": "Україна",
          "en": "Ukraine",
          "ru": "Украина",
          "pl": "Ukraina",
          "de": "Ukraine"
        }
      }
    }
  ],
  "total": 1234,
  "pages": 25
}

Response fields:

  • items - Array of provider objects (max 100 items per page)
  • total - Total number of providers matching your criteria
  • pages - Total number of pages (calculated as: ceil(total / limit))

Detail Response Example

{
  "id": 1,
  "edrpou": "00131305",
  "name": "Public Joint Stock Company Kyiv Energy",
  "website": "https://kyivenergo.ua",
  "description": "Electricity distribution company serving Kyiv",
  "phone": "+380 44 467 0067",
  "country": {
    "id": 1,
    "code": "UA",
    "name": {
      "uk": "Україна",
      "en": "Ukraine",
      "ru": "Украина",
      "pl": "Ukraina",
      "de": "Ukraine"
    }
  },
  "created_at": "2024-01-15T10:30:00+02:00",
  "updated_at": "2024-06-20T14:45:00+02:00"
}

Additional fields in detail view:

  • created_at - When record was added to database (ISO 8601 format)
  • updated_at - Last time record was modified (ISO 8601 format)

Error Responses

404 Not Found - Provider doesn't exist or is inactive

{
  "error": "Service provider not found"
}

Use case: Invalid ID or provider was deactivated in database

Custom Contragents API (Full CRUD)

Custom contragents support full CRUD operations with strict validation:

API Endpoints

GET    /api/v1/user/custom-contragents           # List all user contragents
POST   /api/v1/user/custom-contragents           # Create new contragent
GET    /api/v1/user/custom-contragents/{id}      # Get contragent details
PUT    /api/v1/user/custom-contragents/{id}      # Update contragent
DELETE /api/v1/user/custom-contragents/{id}      # Delete contragent

Authentication required: All endpoints require user authentication. You can only manage your own contragents.

Request Examples

Example 1: Get list of your contragents

Use case: Display all user's custom contragents in expense form dropdown or management page.

GET /api/v1/user/custom-contragents

Example 2: Create new contragent

Use case: User adds new company that is not in official database. Only name field is required, all other fields are optional but validated if provided.

POST /api/v1/user/custom-contragents
Content-Type: application/json

{
  "name": "Example Company LLC",
  "short_name": "Example Co",
  "legal_form": "LLC",
  "tax_number": "12345678",
  "vat_number": "123456789012",
  "iban": "UA123456789012345678901234567",
  "bank_name": "PrivatBank",
  "bank_mfo": "305299",
  "swift": "PBANUA2X",
  "email": "[email protected]",
  "phone": "+380 44 123 4567",
  "website": "https://example.com",
  "director_name": "John Doe",
  "legal_address": "Kyiv, Khreshchatyk St, 1",
  "registration_date": "2020-01-15"
}

Example 3: Get contragent details

Use case: Display full information about specific contragent on detail page.

GET /api/v1/user/custom-contragents/1

Example 4: Update contragent

Use case: User edits contragent information. Send only fields that need to be updated. All validation rules apply.

PUT /api/v1/user/custom-contragents/1
Content-Type: application/json

{
  "phone": "+380 44 999 8888",
  "email": "[email protected]",
  "website": "https://new-website.com"
}

Example 5: Delete contragent

Use case: User removes contragent that is no longer needed. Cannot delete if contragent is used in expenses.

DELETE /api/v1/user/custom-contragents/1

List Response Example

{
  "contragents": [
    {
      "id": 1,
      "name": "Example Company LLC",
      "short_name": "Example Co",
      "legal_form": "LLC",
      "tax_number": "12345678",
      "vat_number": "123456789012",
      "iban": "UA123456789012345678901234567",
      "bank_name": "PrivatBank",
      "bank_mfo": "305299",
      "swift": "PBANUA2X",
      "email": "[email protected]",
      "phone": "+380 44 123 4567",
      "website": "https://example.com",
      "director_name": "John Doe",
      "contact_person": "Jane Smith",
      "legal_address": "Kyiv, Khreshchatyk St, 1",
      "actual_address": "Kyiv, Khreshchatyk St, 1",
      "registration_date": "2020-01-15",
      "notes": "Primary utility provider",
      "created_at": "2024-01-15T10:30:00+02:00",
      "updated_at": "2024-06-20T14:45:00+02:00"
    }
  ]
}

Create/Update Success Response

{
  "id": 1,
  "name": "Example Company LLC",
  "message": "Contragent created successfully"
}

Delete Success Response

{
  "message": "Contragent deleted successfully"
}

Validation Errors Response

Returned with HTTP 400 when validation fails. Contains field names and error messages.

{
  "error": "Validation failed",
  "violations": {
    "name": "Name must be at least 3 characters long",
    "tax_number": "Tax number must be 8-12 digits",
    "iban": "Invalid IBAN format",
    "email": "Invalid email address"
  }
}

403 Forbidden - Access Denied

Returned when trying to access or modify contragent that belongs to another user.

{
  "error": "Access denied"
}

404 Not Found - Contragent Not Found

Returned when contragent with specified ID does not exist.

{
  "error": "Contragent not found"
}

409 Conflict - Cannot Delete

Returned when trying to delete contragent that is used in expenses or other records.

{
  "error": "Cannot delete contragent. It is used in 5 expense records."
}

Swagger / OpenAPI

Full API documentation is available in Swagger UI:

API Documentation

Database Providers

Browse active service providers from the system database