Dokumentacja API — Multiregister

PL Available now

FR In progress

Authentication

Two-step account setup. Register with your email — you'll receive a one-time token by email. Exchange it for a Master Token using /auth/init. The Master Token grants full access to all endpoints and is shown only once — store it securely immediately.

Register

Creates a new account. Authentication is passwordless — no password is required or stored. After registration, a one-time initialization token is sent to your email address. The token expires after 24 hours — use it with /auth/init to generate your Master Token. The user_ref returned is your unique account identifier — keep it handy for support requests.

Body Parameters

Name	Type	Description
email*	string	Your email address. Used for account identification and receiving the initialization token.
name*	string	Account name or label. Used for identification purposes only.

                
Request

POST /api/v1/auth/register

curl -X POST https://api.alexambros.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com",
    "name": "my-integration"
  }'

                
Response · 201 Created

{
  "user_ref":   "3XPT7SS5VG3B",
  "email":      "you@example.com",
  "message":    "Registration successful. Check your email to initialize your account.",
  "expires_at": "2026-03-18T10:48:59+00:00"
}

Initialize Account

Exchanges the one-time token received by email for a Master Token. The Master Token has full access to all endpoints and is used as the Authorization: Bearer header in every subsequent request. Must be called within 24 hours of registration.

⚠ The Master Token is returned only once and cannot be retrieved again. Store it securely immediately — if lost, use /auth/recover.

🎁 Every new account receives 100 bonus credits upon initialization — credited to your wallet automatically, no action required.

Body Parameters

Name	Type	Description
token*	string	The one-time initialization token received by email after registration.

                
Request

POST /api/v1/auth/init

curl -X POST https://api.alexambros.com/api/v1/auth/init \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "token": "6d6c675fcebf98fdbeed11055f98fada..."
  }'

                
Response · 200 OK

{
  "user_ref":      "3XPT7SS5VG3B",
  "email":         "you@example.com",
  "master_token":  "sk_live_5a4a9438c8b8d46836b2dd70bc95d0ee...",
  "token_ref":     "O752ABABBLBE",
  "message":       "Account initialized successfully. Save your Master Token securely - you will not see it again!"
}

Request Recovery

Initiates account recovery. Sends a recovery email to your registered address. The email contains a secure link valid for 24 hours. After clicking the link, you will be guided through a browser-based confirmation flow — all existing tokens are revoked and a new Master Token is generated and shown once.

⚠ Recovery revokes all existing tokens — all active integrations will stop working immediately.

Body Parameters

Name	Type	Description
email*	string	The email address associated with your account.

                
Request

POST /api/v1/auth/recover

curl -X POST https://api.alexambros.com/api/v1/auth/recover \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "you@example.com"
  }'

                
Response · 200 OK

{
  "message":    "If an account with this email exists, a recovery email has been sent.",
  "expires_at": "2026-03-27T09:15:20+00:00"
}

                
Response · 422 Unprocessable

{
  "message": "Recovery confirmation failed",
  "errors":  { "email": ["The email field is required."] }
}

Tokens

API tokens (sk_api_*) are scoped credentials used to authenticate all data requests. They are created from your Master Token and can be revoked or rotated independently. A token has access to all data endpoints — Search, Watchlist, Events, Wallet — but cannot manage other tokens. Token management requires the Master Token (sk_live_*).

⚠ Like the Master Token, the plaintext value of a new API token is shown only once at creation time. Store it immediately.

Create Token

Creates a new API token. Requires the Master Token (sk_live_*) in the Authorization header. The token plaintext is returned only once — store it immediately. Optionally set an expiration in days. If omitted, the token never expires.

Body Parameters

Name	Type	Description
name*	string	Token label — for your reference only. 3–255 chars.
expires_in_days	integer	Optional. Token lifetime in days. 1–365. If omitted, token never expires.

                
Request

POST /api/v1/tokens

curl -X POST https://api.alexambros.com/api/v1/tokens \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-integration",
    "expires_in_days": 90
  }'

                
                
                
            
Response · 201 Created

{
  "success": true,
  "data": {
    "token_ref":  "NAHZ4GW2C26H",
    "name":       "my-integration",
    "expires_at": "2026-06-24T11:10:57+00:00",
    "is_active":  true,
    "plaintext":  "sk_api_4b06f7ebafdd3b3cde52712e12de4a5d...",
    "warning":    "Save this token now - it will never be shown again!"
  },
  "meta": {
    "timestamp": "2026-03-24T11:10:57+00:00"
  }
}
        

List Tokens

Returns all tokens associated with your account. Token plaintexts are never returned here — only metadata. Requires the Master Token.

                
Request

GET /api/v1/tokens

curl https://api.alexambros.com/api/v1/tokens \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Accept: application/json"

            
            
            
        
Response · 200 OK

{
  "success": true,
  "data": [
    {
      "token_ref":    "NAHZ4GW2C26H",
      "name":         "my-integration",
      "expires_at":   "2026-06-24T11:10:57+00:00",
      "last_used_at": "2026-03-27T12:18:29+00:00",
      "last_used_ip": "192.168.1.1",
      "usage_count":  1,
      "is_active":    true,
      "revoked_at":   null,
      "created_at":   "2026-03-27T11:51:21+00:00"
    }
  ],
  "meta": {
    "total":     1,
    "timestamp": "2026-03-29T10:16:33+00:00"
  }
}
    

Get Token

Returns metadata of a specific token. The token_ref is returned at creation time and in the token list. Requires the Master Token.

URL Parameters

Name	Type	Description
token_ref*	string	Token reference identifier returned at creation. E.g. `NAHZ4GW2C26H`

                
Request

GET /api/v1/tokens/{token_ref}

curl https://api.alexambros.com/api/v1/tokens/{token_ref} \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Accept: application/json"

            
            
            
        
Response · 200 OK

{
  "success": true,
  "data": {
    "token_ref":    "NAHZ4GW2C26H",
    "name":         "my-integration",
    "expires_at":   "2026-06-24T11:10:57+00:00",
    "last_used_at": "2026-03-27T12:18:29+00:00",
    "last_used_ip": "192.168.1.1",
    "usage_count":  1,
    "is_active":    true,
    "revoked_at":   null,
    "created_at":   "2026-03-27T11:51:21+00:00"
  },
  "meta": {
    "timestamp": "2026-03-29T10:35:33+00:00"
  }
}
    

Update Token

Updates the label of an existing token. Requires the Master Token.

Body Parameters

Name	Type	Description
name*	string	New token label. 3–255 chars.

                
Request

PUT /api/v1/tokens/{token_ref}

curl -X PUT https://api.alexambros.com/api/v1/tokens/{token_ref} \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production-name-change" }'

            
            
            
        
Response · 200 OK

{
  "success": true,
  "data": {
    "token_ref":    "NAHZ4GW2C26H",
    "name":         "production-name-change",
    "expires_at":   "2026-06-24T11:10:57+00:00",
    "last_used_at": null,
    "last_used_ip": null,
    "usage_count":  0,
    "is_active":    true,
    "revoked_at":   null,
    "created_at":   "2026-03-27T11:51:21+00:00"
  },
  "meta": {
    "timestamp": "2026-03-29T10:41:29+00:00"
  }
}
    

Revoke Token

Permanently revokes a token. The token becomes immediately inactive — any request using it will return 401 Unauthorized. This action cannot be undone. Requires the Master Token.

                
Request

DELETE /api/v1/tokens/{token_ref}

curl -X DELETE https://api.alexambros.com/api/v1/tokens/{token_ref} \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Accept: application/json"

            
Response · 200 OK

{
  "success":  true,
  "message":  "Token revoked successfully",
  "meta": {
    "revoked_at": "2026-03-29T10:44:55+00:00"
  }
}

Verify Token

Checks whether the token in the Authorization header is valid and active. Useful for testing your integration. Works with both Master and API tokens.

                
Request

POST /api/v1/tokens/verify

curl -X POST https://api.alexambros.com/api/v1/tokens/verify \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

            
            
            
        
Response · 200 OK

{
  "success": true,
  "data": {
    "valid":        true,
    "token_ref":    "NAHZ4GW2C26H",
    "token_name":   "my-integration",
    "user_ref":     "3XPT7SS5VG3B",
    "user_name":    "my-integration",
    "expires_at":   "2026-06-27T10:48:53+00:00",
    "is_active":    true,
    "last_used_at": null
  },
  "meta": {
    "timestamp": "2026-03-29T10:49:21+00:00"
  }
}
    

Rotate Token

Revokes the current token and generates a new one with identical settings — same name, same expiration window from today. Use this to rotate credentials without reconfiguring integrations manually. Requires the Master Token.

⚠ The new token plaintext is returned only once. Store it immediately. The old token is revoked instantly.

                
Request

POST /api/v1/tokens/{token_ref}/rotate

curl -X POST https://api.alexambros.com/api/v1/tokens/{token_ref}/rotate \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Accept: application/json"

            
            
            
        
Response · 200 OK

{
  "success": true,
  "data": {
    "old_token": {
      "token_ref":  "NAHZ4GW2C26H",
      "name":       "my-integration",
      "revoked_at": "2026-03-29T10:53:26+00:00",
      "is_active":  false
    },
    "new_token": {
      "token_ref":  "5BCSA3AZ7INF",
      "name":       "my-integration (rotated)",
      "expires_at": "2026-06-27T10:48:53+00:00",
      "is_active":  true,
      "plaintext":  "sk_api_xxxx...",
      "warning":    "Save this token now - it will never be shown again!"
    }
  },
  "meta": {
    "timestamp": "2026-03-29T10:53:26+00:00"
  }
}
    

Wallet

Credit-based billing. Every API operation deducts credits from your wallet balance. Top up your wallet via Paddle — the API returns a checkout URL which you open in a browser to complete payment. Credits are added to your balance automatically after payment confirmation.

Get Wallet

Returns your current credit balance and total credits purchased to date. Works with both Master and API tokens.

                
Request

GET /api/v1/wallet

curl https://api.alexambros.com/api/v1/wallet \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

                
Response · 200 OK

{
  "status": "success",
  "data": {
    "balance":          99845,
    "total_purchased":  100000
  }
}

Top Up

Initiates a wallet top-up. Pass the slug of the credit package you want to purchase. The response contains a checkout_url — open it in a browser to complete payment via Paddle. Credits are added to your balance automatically after confirmation.

Body Parameters

Name	Type	Description
package_slug*	string	Credit package identifier. See available packages on the Pricing page.

                
Request

POST /api/v1/wallet/topup

curl -X POST https://api.alexambros.com/api/v1/wallet/topup \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "package_slug": "pack_10k" }'

                
                
                
            
Response · 200 OK

{
  "status": "success",
  "data": {
    "checkout_url": "https://api.alexambros.com/checkout-pay?_ptxn=txn_01kkxrrc...",
    "package":      "pack_10k",
    "credits":      10000
  }
}
        

Transaction History

Returns a paginated list of wallet transactions — both top-ups (deposits) and API usage (withdrawals). Each entry includes the operation description, amount, and balance after the transaction.

Query Parameters

Name	Type	Description
page	integer	Page number. Default: 1.

                
Request

GET /api/v1/wallet/transactions?page=1

curl "https://api.alexambros.com/api/v1/wallet/transactions?page=1" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

            
            
            
        
Response · 200 OK

{
  "status": "success",
  "data": [
    {
      "type":          "deposit",
      "amount":        "10000.00",
      "balance_after": "10100.00",
      "description":   "Wallet top-up (Paddle)",
      "created_at":    "2026-03-30T08:40:05.000000Z"
    },
    {
      "type":          "start",
      "amount":        "100.00",
      "balance_after": "100.00",
      "description":   "Welcome bonus credits",
      "created_at":    "2026-03-30T06:55:25.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page":    1,
    "per_page":     20,
    "total":        2,
    "next_page":    null,
    "prev_page":    null
  }
}
    

Companies

Search and inspect companies from the Polish business registry. Search returns a lightweight result set — identifiers, name, location, main activity, status, and contacts. Snapshot returns the full entity profile including all addresses, units, activities, dates, and persons.

Search Companies

Search the registry with dynamic filters. All parameters are optional and combinable. Returns up to 20 results per page — each result includes identifiers, name, location, main activity code, status, and verified contact data. Use has_contact to filter only companies that have a specific contact type.

Query Parameters

Name	Type	Description
has_contact	enum	Filter by contact type: `phone`, `email`, `fax`.
activity_code	string	Exact activity code. PL / PKD / without dots E.g. `6201Z`
activity_prefix	string	PKD code prefix — matches all codes starting with this value. E.g. `62`
activity_start_from	date	Filter by activity start date — from. Format: `Y-m-d`.
activity_start_to	date	Filter by activity start date — to. Format: `Y-m-d`.
voivodeship	string	Filter by voivodeship name. E.g. `mazowieckie`
city	string	Filter by city name. Max 150 chars.
postal_code	string	Filter by postal code. Max 20 chars.
status	enum	`ACTIVE`, `SUSPENDED`, `DELETED`. Default: `ACTIVE`.
legal_form	string	Legal form slug from the registry dictionary. See Dictionaries.
page	integer	Page number. Default: 1.

                
Request

GET /api/v1/companies/search

curl "https://api.alexambros.com/api/v1/companies/search?activity_start_from=2026-02-01&activity_start_to=2026-03-01&has_contact=phone" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

                
                
                
            
Response · 200 OK

{
  "status": "success",
  "data": {
    "total":        508254,
    "per_page":     20,
    "current_page": 1,
    "last_page":    25413,
    "results": [
      {
        "identifiers": [
          { "type": "NIP",    "value": "7721824982" },
          { "type": "REGON9", "value": "260343017" }
        ],
        "name":           "GOSPODARSTWO ROLNE KRZYSZTOF NOWAK",
        "city":           "Rączki",
        "voivodeship":    "świętokrzyskie",
        "activity_start": "1998-02-13",
        "activity_main":  "0111Z",
        "status":         "ACTIVE",
        "contacts": [
          { "type": "phone", "value": "515698087" }
        ]
      }
    ]
  }
}
        

Company Snapshot

Returns the full current profile of a company by identifier. A single entity may have multiple profiles — for example a sole trader registered under both a medical practice and a different business activity. The response includes all identifiers, profiles, addresses, local units, activity codes, dates, contacts, websites, and persons associated with the entity.

Body Parameters

Name	Type	Description
identifier_type*	enum	Identifier type: `NIP`, `REGON9`, `KRS`
identifier_value*	string	Identifier value. Max 50 chars.

                
Request

POST /api/v1/companies/snapshot

curl -X POST https://api.alexambros.com/api/v1/companies/snapshot \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "identifier_type": "REGON9",
    "identifier_value": "021168364"
  }'

                
                
                
            
Response · 200 OK

{
  "status": "success",
  "data": {
    "identity": {
      "identifiers": [
        { "type": "NIP",    "value": "6121106077" },
        { "type": "REGON9", "value": "021168364"  }
      ],
      "company_type": "Osoba fizyczna",
      "country_code": "PL"
    },
    "profiles": [
      {
        "name":       "Indywidualna Specjalistyczna Praktyka Lekarska Elżbieta Cieśla",
        "status":     "Aktywny",
        "legal_form": "OSOBY FIZYCZNE PROWADZĄCE DZIAŁALNOŚĆ GOSPODARCZĄ",
        "address": {
          "street":      "ul. staroszkolna",
          "building":    "2a",
          "apartment":   "9",
          "city":        "Bolesławiec",
          "postal_code": "59-700",
          "voivodeship": "dolnośląskie",
          "country_code": "PL"
        },
        "units": [
          {
            "identifier": "02116836400027",
            "name":       "Indywidualna Praktyka Lekarska Elżbieta Cieśla",
            "address":   { /* same structure as above */ },
            "dates": [
              { "type": "Data powstania",             "date": "2013-09-19" },
              { "type": "Data zakończenia działalności", "date": "2015-08-21" }
            ]
          }
        ],
        "contacts":   [],
        "activities": [
          { "code": "8622Z", "name": "PRAKTYKA LEKARSKA SPECJALISTYCZNA", "is_primary": true }
        ],
        "dates": [
          { "type": "Data powstania",           "date": "2026-01-02" },
          { "type": "Data wpisu do regon",      "date": "2026-01-02" }
        ],
        "websites": []
      }
    ],
    "persons": [
      { "full_name": "ELŻBIETA DANUTA CIEŚLA", "role": "Właściciel" }
    ]
  },
  "meta": {
    "fetched_at": "2026-03-24T14:48:49+00:00"
  }
}
        

Watchlist

Monitor companies that matter to you. Add entities to your watchlist by identifier — the system checks for changes daily and generates typed events for every detected difference. You can add up to 100 identifiers in a single request. Adding is asynchronous — you receive an immediate confirmation and a notification by email once the entities are ready to monitor.

Add to Watchlist

Submits one or more companies for watchlist monitoring. Accepts up to 100 identifiers per request. The request returns immediately with Accepted for processing — entities are queued and processed asynchronously.

If the entity already exists in the registry database it is added instantly. If not, it goes through a full import pipeline first. Either way, you receive an email confirmation once all submitted entities are available on your watchlist and ready to receive events.

Body Parameters

Name	Type	Description
identifier_type*	enum	Identifier type: `NIP`, `REGON9`, `KRS`
value*	string[]	Array of identifier values. Max 100 items per request.

                
Request

POST /api/v1/companies/add

curl -X POST https://api.alexambros.com/api/v1/companies/add \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "identifier_type":  "REGON9",
    "identifier_value": ["241150780", "290368057", "543478623"]
  }'

                
Response · 202 Accepted

{
  "success": true,
  "message": "Accepted for processing."
}

List Watched Companies

Returns a paginated list of all companies on your watchlist. Each entry includes the primary identifier, company name, date added, date of the last detected event, and total event count. This endpoint is free — no credits are deducted.

Query Parameters

Name	Type	Description
page	integer	Page number. Default: 1.

                
Request

GET /api/v1/companies/watched

curl "https://api.alexambros.com/api/v1/companies/watched?page=1" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

                
                
                
            
Response · 200 OK

{
  "success": true,
  "data": [
    {
      "primary_identifier": "241150780",
      "name":               "Aleksander Ambros",
      "watched_since":      "2026-03-24",
      "last_event_at":      null,
      "events_count":       0
    },
    {
      "primary_identifier": "790313678",
      "name":               "LIPIŃSKI MARCIN",
      "watched_since":      "2026-03-18",
      "last_event_at":      null,
      "events_count":       6
    }
  ],
  "meta": {
    "total":        38,
    "per_page":     20,
    "current_page": 1,
    "last_page":    2
  }
}
        

Remove from Watchlist

Removes one or more companies from your watchlist. Uses the same identifier format as /companies/add. The response details which identifiers were removed, which were not found in the registry, and which were not on your watchlist. Daily monitoring stops immediately for removed entities.

Body Parameters

Name	Type	Description
name*	enum	Identifier type: `NIP`, `REGON9`, `KRS`
value*	string[]	Array of identifier values to remove.

                
Request

DELETE /api/v1/companies/watched

curl -X DELETE https://api.alexambros.com/api/v1/companies/watched \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "identifier_type":  "REGON9",
    "identifier_value": ["241150780"]
  }'

                
                
                
            
Response · 200 OK

{
  "success": true,
  "data": {
    "removed":     ["241150780"],
    "not_found":   [],
    "not_watched": []
  },
  "meta": {
    "total":      1,
    "removed":    1,
    "not_found":  0,
    "not_watched": 0,
    "removed_at": "2026-03-24T15:18:25+00:00"
  }
}
        

Company Events

Returns the full event history for a specific company identified by NIP, REGON9, or KRS. Unlike /watchlist/events which returns a feed across your entire watchlist, this endpoint focuses on a single entity and returns all detected changes for it. Optionally filter by event type and date range.

Query Parameters

Name	Type	Description
identifier_type*	enum	Required. Identifier type: `NIP`, `REGON9`, `KRS`
identifier_value*	string	Identifier value of the company.
page	integer	Page number. Default: 1.
per_page	integer	Results per page. Default: 20.

                
Request

GET /api/v1/companies/events

curl "https://api.alexambros.com/api/v1/companies/events?identifier_type=NIP&identifier_value=6842685591" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

                
                
                
            
Response · 200 OK

{
  "status": "success",
  "data": {
    "events": [
      {
        "event_type": "COMPANY_NAME_CHANGED",
        "old_value":  "Ireneusz Kupiec",
        "new_value":  "Ireneusz Kupiec wspólnik spółki cywilnej RAZBUD S.C.",
        "event_date": "2025-10-06",
        "severity":   "info"
      },
      {
        "event_type": "COMPANY_CLOSED_DATE",
        "old_value":  null,
        "new_value":  "2026-02-28",
        "event_date": "2025-10-06",
        "severity":   "info"
      }
    ]
  },
  "meta": {
    "total":        8,
    "per_page":     20,
    "current_page": 1,
    "last_page":    1,
    "fetched_at":   "2026-03-24T15:20:44+00:00"
  }
}
        

Watchlist Events Feed

Returns a paginated feed of all events detected across your entire watchlist. Unlike /companies/events which focuses on a single entity, this endpoint aggregates changes from all your monitored companies. Filter by event type, date range, and scope. Returns 20 events per page.

Query Parameters

Name	Type	Description
event_type	string	Filter by event type. E.g. `COMPANY_NAME_CHANGED`.
from_date	date	Start date. Format: `Y-m-d`.
to_date	date	End date. Format: `Y-m-d`.
page	integer	Page number. Default: 1.
per_page	integer	Results per page. Default: 20.

                
Request

GET /api/v1/watchlist/events

curl "https://api.alexambros.com/api/v1/watchlist/events?from_date=2026-03-01&to_date=2026-03-24" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

                
                
                
            
Response · 200 OK

{
  "status": "success",
  "data": [
    {
      "primary_identifier": "543701794",
      "identifier_type":               "CAR-PRO MAX DETAILING",
      "event_type":         "COMPANY_START_DATE_CHANGE",
      "old_value":          "2026-02-25",
      "new_value":          "2026-03-02",
      "event_date":         "2026-03-02",
      "severity":           "info"
    }
  ],
  "meta": {
    "total":        170,
    "per_page":     20,
    "current_page": 1,
    "last_page":    9,
    "fetched_at":   "2026-03-24T15:55:25+00:00"
  }
}
        

Stats

Global registry statistics sourced from GUS — daily snapshots and date-range aggregates. All endpoints in this group are rate-limited to 10 requests per minute. No authentication required.

Stats — Range

Returns aggregated registry activity from the beginning of data up to and including the given date. The response includes a meta object with the resolved date range and data source.

Path Parameters

Name	Type	Description
date required	string	End date in `YYYY-MM-DD` format. Returns all records up to this date.

                
Request

GET /api/v1/stats/range/2026-04-01

curl "https://api.alexambros.com/api/v1/stats/range/2026-04-01" \
  -H "Accept: application/json"

                
                
                
            
Response · 200 OK

{
  "meta": {
    "from_date":   "2026-04-01",
    "to_date":     "2026-04-08",
    "source":     "GUS",
    "description":"Registry activity in Poland for the given date range"
  },
  "data": {
    "new":     6941,
    "updated": 41571,
    "deleted": 5690,
    "total":   54202
  }
}
        

Stats — Single Day

Returns a daily snapshot for a specific date — how many companies were added, updated or removed from the Polish registry on that day. The meta.type field will always be daily_snapshot.

Path Parameters

Name	Type	Description
date required	string	Target date in `YYYY-MM-DD` format.

                
Request

GET /api/v1/stats/day/2026-04-01

curl "https://api.alexambros.com/api/v1/stats/day/2026-04-01" \
  -H "Accept: application/json"

                
                
                
            
Response · 200 OK

{
  "meta": {
    "date":        "2026-04-01",
    "type":        "daily_snapshot",
    "source":      "GUS",
    "description": "Daily registry activity in Poland"
  },
  "data": {
    "new":     1507,
    "updated": 12665,
    "deleted": 2057,
    "total":   16229
  }
}
        

Error Reference

All API errors return JSON. Depending on the error type, the response shape differs slightly — see each status code below for the exact format.

401 — Unauthorized

Returned when the token is missing or malformed.

                
Missing token

{
  "error": "Missing API token",
  "code":  "UNAUTHORIZED"
}

                
Malformed token

{
  "error": "Malformed token format",
  "code":  "UNAUTHORIZED"
}

404 — Not Found

Returned when a route or resource does not exist.

                
Route not found

{
  "message": "The route api/v1/stats/day could not be found."
}

422 — Validation Error

Returned when request body fails validation. The errors object contains field-level messages — always check each key separately.

                
                
                
            
Validation failed

{
  "message": "The email field must be a valid email address. (and 1 more error)",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ],
    "name": [
      "The name field is required."
    ]
  }
}
        

429 — Too Many Requests

Returned when you exceed the rate limit. Stats endpoints allow 10 requests per minute. Back off and retry after a moment.

                
Rate limit exceeded

{
  "message": "Too Many Attempts."
}

500 — Server Error

Something went wrong on our end. If this persists, contact contact@alexambros.com.

                
Internal server error

{
  "message": "Server Error"
}