OpenRegister Documentation
⌘ K
Checking API v1
Developer APIStable v1

One schema for registers in different countries.

Search companies through normalised JSON and return to the national fields, source file and hash whenever you need them.

Get an API key Send your first request ↓
PROVENANCE TRACE
  1. 01
    SOURCE FILEregistry.csv
  2. 02
    INTEGRITYsha256 verified
  3. 03
    NORMALIZElegal_entity
  4. 04
    RESPONSEGET /entities/{id}
BASE URLhttps://md.hanta.io/api/v1

Quickstart

From key to data in three steps

Every data endpoint uses the same authentication contract. You do not need an SDK; any HTTP client will work.

  1. 1

    Create a key

    Open the API account, name the environment and save the secret immediately — it will not be shown again.

    Open API account →
  2. 2

    Send the key in a header

    Use X-API-Key or Bearer. The API console already has the correct URL and parameters.

  3. 3

    Save the request ID

    The response includes X-Request-ID. Send it to support when investigating a specific request.

Authentication

An API key belongs to an environment

Create separate keys for production, staging and analytics. A key acts for the account and uses its shared monthly quota.

Recommended

X-API-Key

X-API-Key: or_live_…
Compatible alternative

Bearer token

Authorization: Bearer or_live_…
Only you hold the key.

OpenRegister stores only a SHA-256 hash. Never put the secret in a query string, frontend bundle, log or public repository.

Registry APIX-API-Key

Server integrations and data requests.

Account APIClerk session

Account, keys and subscription management.

Stripe webhookStripe-Signature

Signed events from Stripe only.

Pagination

Pages with a predictable size

Search results are sorted by name and stable ID. Use the values in meta instead of calculating the number of pages in the client.

page1…N

Number of the requested page.

pageSize1…100

Returns 25 records by default.

meta.totalinteger

Number of records matching the current filter.

meta.pageCountinteger

Number of available pages.

Limits and quotas

Two counters for every request

The per-minute limit protects the API from spikes; the monthly quota limits plan volume. Both counters are returned after every successful data request.

HeaderValue
X-RateLimit-LimitRequest limit per minute.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetUnix timestamp when the window resets.
X-Monthly-Quota-LimitBilling-period quota.
X-Monthly-Quota-RemainingRequests remaining in the period.
X-Monthly-Quota-ResetStart of the new period in ISO 8601 format.
Received a 429?Read Retry-After, add random jitter and retry the request.

Errors

One error shape for every endpoint

Handle error.code in your application and write message to the logs. requestId links the error to the server request.

ERROR · 401 
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or revoked",
    "requestId": "69a27c71-44ab-4c0c-a95d-1a1ea8da24cc",
    "docs": "https://md.hanta.io/docs/api"
  }
}
400invalid_request

A parameter or UUID has an invalid format.

401api_key_required

The API key header is missing.

401invalid_api_key

The key is unknown, revoked or malformed.

404entity_not_found

No record was found with this OpenRegister ID.

429rate_limit_exceeded

The key’s per-minute limit has been exhausted.

429monthly_quota_exceeded

The billing-period quota has been exhausted.

Versioning

The version is fixed in the URL

The current stable contract is /api/v1. Within v1 we may add nullable fields and new endpoints, but we do not remove fields or change their type without a new version.

Machine-readable contractOpenAPI 3.1 JSON
Download ↗

API reference

Registry API endpoints

All three endpoints require an API key and return rate-limit headers. Select “Show example” to open a ready-made request in the console.

GET/countries

List countries

Registers that are available now or planned.

API key application/json

No parameters required.

GET/entities

Search companies

Search by name or IDNO with filters and stable pagination.

API key application/json

Parameters

qstring

Case-insensitive part of a company name or registration number.

countrystring

Two-letter ISO 3166-1 country code.

legalFormstring

Exact national value of the legal form.

activitystring

Activity code or a Russian or Romanian name fragment.

activityTypeunlicensed | licensed

Activity list type: unlicensed or licensed.

registeredWithin7d | 30d | 90d | 1y

Rolling registration period: 7, 30, 90 days or 1 year.

registeredFromdate

Inclusive registration-date lower bound in YYYY-MM-DD format.

registeredTodate

Inclusive registration-date upper bound in YYYY-MM-DD format.

includeClosedboolean

Include closed companies. They are excluded by default.

sortname | newest | updated

Order by name, registration date or last update.

pageinteger

Page number. Defaults to 1.

pageSizeinteger

Page size from 1 to 100. Defaults to 25.

GET/entities/{id}

Retrieve a complete company record

Normalised fields, national record and source provenance.

API key application/json

Parameters

iduuidrequired

OpenRegister ID from a search result.

API reference

Entity object

Normalised fields are the same for every country. The national structure remains in registry and sourceData, so adding countries does not break the shared contract.

iduuid

Stable OpenRegister identifier.

countryCodestring

ISO 3166-1 alpha-2 jurisdiction code.

canonicalNamestring

Name used for search and display.

statusstring

Normalised record status.

legalFormstring | null

National legal form.

registryobject

Typed and resolved national fields.

sourceDataobject

Original fields without loss or renaming.

registrationsarray

Registration numbers and local statuses.

provenanceobject | null

File, hash, import date and primary source URL.

API plans

Fixed pricing with no overages

When the quota is exhausted, the API stops requests with 429 — there is no unexpected bill.

GET/api/v1/planspublic

Free

€0/ month

For prototypes and API evaluation

  • 1,000 requests / period
  • 60 requests / minute
  • 1 active API key slots

Pro

Popular
€9.99/ month

For production integrations

  • 100,000 requests / period
  • 600 requests / minute
  • 5 active API key slots

Business

€29.99/ month

For high volumes and multiple environments

  • 1,000,000 requests / period
  • 3,000 requests / minute
  • 20 active API key slots

Account endpoints

Account, company lists and delivery

These endpoints manage the account, keys, materialized company lists and outbound webhooks. They use a Clerk token or session cookie; a Registry API key is not valid for them.

GET /api/v1/account

Plan, usage, billing status and active keys.

GET /api/v1/auth/me

Current Clerk user profile.

GET /api/v1/api-keys

List active keys without their secrets.

POST /api/v1/api-keys

Create a key and return the full secret once.

DELETE /api/v1/api-keys/{id}

Revoke a key belonging to the current account.

GET /api/v1/saved-searches

List saved searches and their live result URLs.

POST /api/v1/saved-searches

Save company-directory criteria.

PUT /api/v1/saved-searches/{id}

Replace a saved search.

DELETE /api/v1/saved-searches/{id}

Delete a saved search owned by the current account.

GET /api/v1/lists

List materialized company lists and their record counts.

POST /api/v1/lists

Create an empty company list.

GET /api/v1/lists/{id}

Get a paginated list of companies, connections and delivery history.

PUT /api/v1/lists/{id}

Replace a list name and description.

DELETE /api/v1/lists/{id}

Delete a company list.

POST /api/v1/lists/{id}/items

Add a company and queue new outbound deliveries.

DELETE /api/v1/lists/{id}/items/{entityId}

Remove a company from a list.

GET /api/v1/webhook-endpoints

List outbound delivery endpoints without secrets.

POST /api/v1/webhook-endpoints

Create a universal JSON webhook endpoint or use the optional Hanta preset.

PATCH /api/v1/webhook-endpoints/{id}

Enable or disable an endpoint.

DELETE /api/v1/webhook-endpoints/{id}

Disable an endpoint while preserving its history.

PUT /api/v1/lists/{id}/webhook-endpoints/{endpointId}

Attach an outbound endpoint to a list.

DELETE /api/v1/lists/{id}/webhook-endpoints/{endpointId}

Detach an outbound endpoint from a list.

POST /api/v1/webhook-deliveries/{id}/retry

Requeue a failed outbound delivery.

Service health

GET/api/v1/health/live

The process is running and accepting HTTP requests.

GET/api/v1/health/ready

The application and PostgreSQL are ready to accept traffic.

Stripe billing

Checkout and subscription

Paid plans use Stripe Checkout. Invoices, payment methods, plan changes and cancellation are available through the Stripe Customer Portal in the API account.

1CheckoutCreate subscription
→
2WebhookVerify status
→
3EntitlementsNew API limits

Access changes only after a signed Stripe webhook event, not after the redirect from Checkout.

Billing endpoints

GET /api/v1/plans

Public catalogue of plans and entitlements.

POST /api/v1/billing/checkout

Create a Stripe Checkout session.

POST /api/v1/billing/portal

Create a Stripe Customer Portal session.

POST /api/v1/billing/webhook

Internal endpoint protected by the Stripe-Signature header.

Supported events
checkout.session.completedcustomer.subscription.createdcustomer.subscription.updatedcustomer.subscription.deletedcustomer.subscription.pausedcustomer.subscription.resumed

The event ID is saved before processing, making repeat delivery safe. An older event never overwrites a newer subscription state.