SDKs & Libraries

Both SDKs include a sandbox mode that lets you test without an API key and without rate limits. The sandbox returns demo data and works the same as the production API.

use FirmApi\Client;

$client = Client::sandbox();

// Works the same as production
$company = $client->companies->byIco('51636549')->get();

import { FirmApi } from 'firmapi';

const client = FirmApi.sandbox();

// Works the same as production
const company = await client.companies.byIco('51636549');

Official PHP client for FirmAPI. Requires PHP 8.1+ and supports Laravel auto-discovery.

Installation

Quick Start

use FirmApi\Client;

// Create a client with your API key
$client = new Client('your-api-key');

// Look up a company by ICO (base data only)
$company = $client->companies->byIco('51636549')->get();

echo $company['data']['name'];         // "Version Two s. r. o."
echo $company['data']['address'];       // "Bratislava ..."

// Include enrichment data with fluent methods
$company = $client->companies->byIco('51636549')
    ->withTax()
    ->withFinancials()
    ->withDebtorStatus()
    ->get();

echo $company['data']['tax']['dic'];          // "2120733417"
echo $company['data']['financials']['revenue']; // 12500000

// Or get everything at once
$full = $client->companies->byIco('51636549')->withAll()->get();

// Search by name
$results = $client->search->byName('Version Two');

foreach ($results['data'] as $company) {
    echo $company['ico'] . ' - ' . $company['name'];
}

// Autocomplete (Select2-compatible)
$suggestions = $client->search->autocomplete('vers', limit: 5);

// Advanced multi-field search
$results = $client->search->advanced([
    'name' => 'Version',
    'city' => 'Bratislava',
]);

// Batch lookup by ICO
$batch = $client->batch->byIco(['51636549', '12345678', '87654321']);

// Check batch status
$status = $client->batch->status($batch['id']);

// Get results
$results = $client->batch->results($batch['id']);

use FirmApi\Exceptions\AuthenticationException;
use FirmApi\Exceptions\RateLimitException;
use FirmApi\Exceptions\ValidationException;
use FirmApi\Exceptions\ApiException;

try {
    $company = $client->companies->byIco('51636549')->get();
} catch (AuthenticationException $e) {
    // Invalid or missing API key (401)
} catch (RateLimitException $e) {
    // Rate limit exceeded (429)
    $retryAfter = $e->getRetryAfter(); // seconds
} catch (ValidationException $e) {
    // Validation error (422)
    $errors = $e->getErrors();
} catch (ApiException $e) {
    // Other API error
    $statusCode = $e->getCode();
}

All Available Methods

Available Enrichment Scopes

Official JavaScript client for FirmAPI. Works in Node.js 18+ and modern browsers with full TypeScript support.

Installation

Quick Start

import { FirmApi } from 'firmapi';

// Create a client with your API key
const client = new FirmApi('your-api-key');

// Look up a company by ICO (base data only)
const company = await client.companies.byIco('51636549');

console.log(company.data.name);    // "Version Two s. r. o."
console.log(company.data.address); // "Bratislava ..."

// Include enrichment data with fluent methods
const detailed = await client.companies.byIco('51636549')
  .withTax()
  .withFinancials()
  .withDebtorStatus();

console.log(detailed.data.tax.dic);          // "2120733417"
console.log(detailed.data.financials.revenue); // 12500000

// Or get everything at once
const full = await client.companies.byIco('51636549').withAll();

// Full configuration
const client = new FirmApi({
  apiKey: 'your-api-key',
  timeout: 30000,             // ms (default: 30000)
  waitForFreshData: true,     // auto-retry stale data (default: true)
  maxStaleRetries: 3,         // max retry attempts (default: 3)
});

// Search by name
const results = await client.search.byName('Version Two');

for (const company of results.data) {
  console.log(`${company.ico} - ${company.name}`);
}

// Autocomplete (Select2-compatible)
const suggestions = await client.search.autocomplete('vers', 5);

// Advanced multi-field search
const advanced = await client.search.advanced({
  name: 'Version',
  city: 'Bratislava',
});

// Batch lookup by ICO
const batch = await client.batch.byIco([
  '51636549',
  '12345678',
  '87654321',
]);

// Check batch status
const status = await client.batch.status(batch.id);

// Get results when completed
const results = await client.batch.results(batch.id);

import {
  FirmApi,
  AuthenticationException,
  RateLimitException,
  ValidationException,
  ApiException,
} from 'firmapi';

try {
  const company = await client.companies.byIco('51636549');
} catch (e) {
  if (e instanceof AuthenticationException) {
    // Invalid or missing API key (401)
  } else if (e instanceof RateLimitException) {
    // Rate limit exceeded (429)
    console.log(e.retryAfter); // seconds
  } else if (e instanceof ValidationException) {
    // Validation error (422)
    console.log(e.errors);
  }
}

All Available Methods