API Documentation

Programmatic access to Kosovo's business registry. Search 240,000+ companies, look up by NUI, stream new registrations, and live-verify records against the official registry.

View pricing →Get API key

Base URL

The API is served from the dedicated API subdomain with clean, versioned paths. This is the recommended base URL:

text

https://api.atlas-studio.eu/v1

The same endpoints are also reachable on each product subdomain under an /api/v1 prefix (no DNS change required):

text

https://arbk.atlas-studio.eu/api/v1

Country scope (Kosovo / Albania) is determined by your API key, not the host — one key works on either base URL and returns only the countries it is licensed for. All examples below use the recommended api.atlas-studio.eu/v1 base.

Authentication

API access is available on the Enterprise plan only. Once you're on Enterprise, generate keys from your account page. Send your key as a Bearer token on every request (the legacy X-API-Key header is also accepted):

bash

# Recommended: Authorization: Bearer
curl -H "Authorization: Bearer atlas_your_key_here" \
  "https://api.atlas-studio.eu/v1/businesses?q=restaurant"

# Also accepted: X-API-Key
curl -H "X-API-Key: atlas_your_key_here" \
  "https://api.atlas-studio.eu/v1/businesses?q=restaurant"

Keys are secret — send them only over HTTPS and never embed them in client-side code.

Rate Limits

The API meters on a monthly call allowance, negotiated as part of your Enterprise contract and enforced per account. Most endpoints cost 1 call; the live /verify endpoint costs 3 (it performs a live government-registry scrape), and a batch verify costs 3 per submitted NUI.

Every response echoes your allowance and usage in the X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (start of next month, UTC) and X-Usage-Month headers. When you exceed the allowance the API returns 429 with a Retry-After header.

GET /businesses

Full-text search and filtering across all registered businesses in Kosovo. Returns the standard { data, meta } envelope with clean English field names. Results are scoped to the countries your API key is licensed for.

Deprecation: the old GET /search endpoint (raw registry column names, daily quota) is deprecated. It now permanently redirects (301) to this endpoint with its legacy params translated. Call /businesses directly.

Parameters

Param	Type	Description
`q`	string	Full-text query (name, NUI, owner, phone)
`nui`	string	Exact NUI lookup (returns a 0- or 1-element collection)
`status`	string	active \| inactive \| suspended
`business_type`	string	Registry business type (e.g. "Shoqëri me përgjegjësi të kufizuara")
`municipality`	string	Municipality (e.g. "Prishtinë")
`region`	string	Location / region (substring match)
`activity_code`	string	NACE code. Repeat or comma-separate for multiple (e.g. activity_code=4711,5610)
`capital_min`	number	Minimum registered capital
`capital_max`	number	Maximum registered capital
`employee_min`	integer	Minimum employee count
`employee_max`	integer	Maximum employee count
`has_email`	boolean	Only businesses with an email on file
`has_phone`	boolean	Only businesses with a phone on file
`has_website`	boolean	Only businesses with a website on file
`has_contact`	boolean	Only businesses with an email or phone on file
`date_registered_from`	string	Registered on/after this date (YYYY-MM-DD)
`date_registered_to`	string	Registered on/before this date (YYYY-MM-DD)
`sort_by`	string	relevance \| name \| nui \| municipality \| status \| business_type \| registration_date \| capital \| employees
`sort_dir`	string	"asc" or "desc" (default: desc)
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 20, max 100 — capped by plan)

Example Response

json

{
  "data": [
    {
      "nui": "811234567",
      "name": "COFFEE SHOP PRISHTINA",
      "trade_name": "Coffee Shop",
      "status": "active",
      "status_raw": "Regjistruar",
      "registration_date": "2020-03-15",
      "closure_date": null,
      "business_type": "Biznes individual",
      "activity_code": "5610",
      "activity_description": "Restaurant activities",
      "municipality": "Prishtinë",
      "region": "Prishtinë",
      "address": "Rr. Example 1",
      "capital": 5000,
      "capital_currency": "EUR",
      "employees": 3,
      "fiscal_number": null,
      "business_number": null,
      "email": "[email protected]",
      "phone": "+38344123456",
      "website": "https://example.com",
      "representative": "John Doe",
      "owners": [{ "name": "John Doe", "ownership_percent": 100 }],
      "country": "XK"
    }
  ],
  "meta": { "total": 1432, "page": 1, "per_page": 20, "total_pages": 72 }
}

GET /businesses/{nui}

Full record for a single business by its Unique Identification Number (NUI). Returns the bare business object (same fields as a search result, no { data } wrapper). For Albania, owners are enriched with real ownership percentages. Returns 404 if the NUI is not in scope or does not exist.

Param	Type	Description
`nui`required	string	Business NUI (path segment)

bash

curl -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/businesses/811234567"

Kosovo records include a rich_fields summary (branch + role-history counts); fetch the full lists from the two endpoints below.

GET /businesses/{nui}/units

Physical branch units ("Njësitë") of a business — each with its unit number, name, per-branch activity code, municipality and place. Paginated { data, meta } envelope. Kosovo only; an Albania or out-of-scope NUI returns an empty collection.

Param	Type	Description
`nui`required	string	Business NUI (path segment)
`page / per_page`	integer	Pagination (per_page default 50, max 200)

bash

curl -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/businesses/811234567/units"

GET /businesses/{nui}/role-history

Full role-change timeline — every owner/shareholder, representative/director and board member, with start/end dates and ownership percentages. Active stints first. Paginated { data, meta } envelope. Kosovo only.

Param	Type	Description
`nui`required	string	Business NUI (path segment)
`role_group`	string	Optional filter: owner \| representative \| board
`page / per_page`	integer	Pagination (per_page default 50, max 200)

bash

curl -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/businesses/811234567/role-history?role_group=owner"

GET /businesses/new

Newly registered (active) businesses within a date window — a sales/lead feed, newest first. Same { data, meta } envelope and the same filters as /businesses (business_type, municipality, region, activity_code, capital/employee ranges, has_*).

Param	Type	Description
`date_from`required	string	Window start (YYYY-MM-DD)
`date_to`required	string	Window end, inclusive (YYYY-MM-DD)
`sort_by / sort_dir`	string	Optional sort (default: registration_date desc)
`page / per_page`	integer	Pagination (per_page default 20, max 100)

bash

curl -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/businesses/new?date_from=2026-01-01&date_to=2026-03-31&municipality=Prishtinë"

GET /businesses/{nui}/verify

Live cross-check of a business against the official ARBK government registry, with a field-by-field diff (name, status, address, capital, owners). Kosovo (XK) only. Costs 3 calls (it performs a live scrape). Results are cached briefly, so repeated checks within the cache window are served without a new scrape (source: "cache").

Param	Type	Description
`nui`required	string	Business NUI (path segment), Kosovo only

Example Response

json

{
  "nui": "811234567",
  "verified_at": "2026-06-08T14:07:29.507Z",
  "match": true,
  "live": true,
  "source": "live",
  "our_record":        { "name": "...", "status": "...", "address": "...", "capital": 5000, "owners": "..." },
  "government_record":  { "name": "...", "status": "...", "address": "...", "capital": 5000, "owners": "..." },
  "changes_detected": [{ "flag": "NO_CHANGES" }]
}

When the registry is temporarily unreachable the endpoint returns 503; retry shortly.

POST /businesses/verify-batch

Queue a batch of NUIs for live verification (Kosovo). Charges 3 calls per (deduplicated) NUI up front and returns a 202 with a job_id. Poll the job or supply a webhook_url (https) to receive the result. Up to 1000 NUIs per batch.

Request body (JSON)

Param	Type	Description
`nuis`required	string[]	Array of NUIs to verify (1–1000)
`webhook_url`	string	Optional https URL to POST the result to on completion

bash

curl -X POST -H "Authorization: Bearer atlas_your_key" \
  -H "Content-Type: application/json" \
  -d '{"nuis":["811234567","810000000"]}' \
  "https://api.atlas-studio.eu/v1/businesses/verify-batch"

Poll a job

GET /businesses/verify-batch/{job_id}

bash

curl -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/businesses/verify-batch/JOB_ID"

GET /digest/weekly

A weekly registry digest — new registrations, deregistrations and status changes — for the week containing week_of (defaults to the current week). Country scope follows your API key.

Param	Type	Description
`week_of`	string	Any date in the target week (YYYY-MM-DD). Defaults to current week.
`municipality`	string	Optional municipality scope
`activity_code`	string	Optional NACE code scope

bash

curl -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/digest/weekly?week_of=2026-06-01"

GET /autocomplete

Business name suggestions for search-as-you-type interfaces. Returns a lightweight array of matches.

Param	Type	Description
`q`required	string	Search query (min 2 characters)
`limit`	integer	Max results (default: 8, max: 50)

bash

curl -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/autocomplete?q=atlas&limit=5"

GET /suppressions

The GDPR delisting / erasure feed — NUIs whose records we have redacted on a verified data-subject request. If you store or cache exported data, poll this to honour suppression obligations. Not country-scoped (a suppression applies everywhere).

Param	Type	Description
`since`	string	ISO-8601 timestamp — only redactions applied at/after this
`limit`	integer	Page size (default 1000, max 5000)
`offset`	integer	Pagination offset

bash

curl -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/suppressions?since=2026-01-01T00:00:00Z"

Error Codes

Errors return a stable envelope with an HTTP status and a machine-readable code:

json

{ "error": { "code": "VALIDATION_ERROR", "message": "status must be one of: active, inactive, suspended", "docs": "https://docs.atlas-studio.eu/errors" } }

HTTP	Code	Meaning
`400`	`VALIDATION_ERROR`	Invalid or missing parameters
`401`	`UNAUTHORIZED`	Missing or invalid API key
`403`	`FEATURE_NOT_IN_PLAN`	Your plan does not include API access
`404`	`NOT_FOUND`	No NUI / resource in scope
`429`	`RATE_LIMIT_EXCEEDED`	Monthly call allowance exceeded (see Retry-After)
`503`	`SERVICE_UNAVAILABLE`	Temporary upstream/registry issue — retry

Code Examples

JavaScript / Node.js

javascript

const API_KEY = "atlas_your_key_here";
const BASE = "https://api.atlas-studio.eu/v1";
const auth = { headers: { Authorization: `Bearer ${API_KEY}` } };

// Search for restaurants in Prishtinë that have a phone on file
const res = await fetch(
  `${BASE}/businesses?q=restaurant&municipality=Prishtinë&has_phone=true&per_page=10`,
  auth
);
const { data, meta } = await res.json();
console.log(`Found ${meta.total} businesses`);

// Full record for one business
const biz = await fetch(`${BASE}/businesses/811234567`, auth).then(r => r.json());
console.log(biz.name, biz.registration_date);

Python

python

import requests

API_KEY = "atlas_your_key_here"
BASE = "https://api.atlas-studio.eu/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Search with filters
resp = requests.get(f"{BASE}/businesses", headers=headers, params={
    "q": "restaurant",
    "municipality": "Prishtinë",
    "capital_min": 5000,
    "sort_by": "capital",
    "sort_dir": "desc",
    "per_page": 10,
})
body = resp.json()
print(f"Found {body['meta']['total']} businesses")

# New registrations this quarter
new = requests.get(f"{BASE}/businesses/new", headers=headers,
                   params={"date_from": "2026-01-01", "date_to": "2026-03-31"}).json()
print(len(new["data"]), "new businesses")

cURL

bash

# Search + filter
curl -s -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/businesses?q=restaurant&municipality=Prishtinë&has_website=true" | jq .

# Newly registered businesses in a date range
curl -s -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/businesses/new?date_from=2026-01-01&date_to=2026-03-31" | jq .

# Full business record
curl -s -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/businesses/811234567" | jq .

# Autocomplete
curl -s -H "Authorization: Bearer atlas_your_key" \
  "https://api.atlas-studio.eu/v1/autocomplete?q=atlas" | jq .