Follow new formations
Poll the formations feed on created_at and never miss a new company.
The shape of it
every few minutes → GET /formations?created_at[gte]=<T − 10 min> → page to the end → dedupe by id → T = newest created_atA formation is a company whose first register entry is a new registration, not a move of the
registered office, a conversion or a merger. The list is ordered by the Registertag
(registration_date), newest first. That is the order you want to read, and the wrong one to
poll on.
Why not poll on the Registertag
- Late finds. Some formations are found a day or more after their Registertag. They sort into the middle of the list, below rows you already read, so paging from the top stops before it reaches them.
- Visible after discovery. A formation is published once the company's first register entry has been written, and the list is refreshed about once a minute.
created_at is the moment a formation became available through the API. Every formation you
have not seen yet has a created_at later than your last poll, whatever its Registertag.
Poll
from datetime import datetime, timedelta, timezone
OVERLAP = timedelta(minutes=10)
def poll(since: datetime, seen: set[str]) -> datetime:
newest = since
params = {"created_at[gte]": (since - OVERLAP).strftime("%Y-%m-%dT%H:%M:%SZ"), "limit": 100}
while True:
r = session.get(f"{BASE}/formations", params=params)
r.raise_for_status()
page = r.json()
for formation in page["data"]:
if formation["id"] in seen: # the overlap re-reads a few; that is its job
continue
seen.add(formation["id"])
handle(formation)
created = datetime.fromisoformat(formation["created_at"].replace("Z", "+00:00"))
newest = max(newest, created)
if page["next_cursor"] is None:
return newest # store it; it is the next `since`
params["cursor"] = page["next_cursor"]Three rules:
- Overlap by ten minutes and deduplicate by
id. Delivery is at-least-once and eventually consistent: a formation appears some time after we find the company, and itscreated_atis the moment it appeared, so the overlap catches it. Keep the ids of the last hour or so; that is enough. - Page forward with
cursoruntilnext_cursorisnull. The order is stable (registration_date, then the order we found them in, thenid, all descending), so a row that arrives while you page is never served twice in one walk and is caught by the next poll. - Every page costs 10 credits. Poll every few minutes, not every few seconds, and keep
limit=100: a quiet interval is one page.
Filters combine with the poll. legal_form=gmbh&legal_form=ug&state=DE-BY follows new GmbHs
and UGs in Bavaria; capital[gte]=25000 only the ones with at least 25,000 EUR of capital.
GET /legal-forms lists every legal_form.
curl -G -g https://api.registercheck.de/v1/formations \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY" \
-d "created_at[gte]=2026-09-30T14:00:00Z" \
-d "legal_form=gmbh" \
-d "legal_form=ug" \
-d "state=DE-BY" \
-d "capital[gte]=25000" \
-d "limit=100"-g stops curl from reading the square brackets as a glob pattern. To look back over a range
of Registertage instead, bound registration_date[gte] and registration_date[lte].
Keep your own notes on a formation
session.patch(f"{BASE}/formations/{formation_id}",
json={"metadata": {"crm_id": "0015g00000XyZ", "stage": "contacted"}})Metadata merges: a key you set is added or replaced, a key set to null is removed, and a key you
do not name is left alone. It belongs to your workspace; nobody else sees it. A formation stays
retrievable with its metadata after it leaves the list's 180-day window. Each update costs 1
credit and returns the formation.
What to know
- The window. The list covers the last 180 days of Registertage. Without a
registration_dateorcreated_atbound it shows the last 30. - Completeness. Registertage before 2026-09-09 are incomplete.
- Right after a restart the list can answer
503withRetry-After. Wait that many seconds and poll again with the samesince; nothing was charged.