Asking for data to be fetched again
What v1 does today when data is missing, and what is not available yet.
Some work cannot happen inside a request: fetching a document from the register, or rebuilding a shareholder history from filed documents. v1 describes that work as a job — you ask for it, get a job back, and poll until it finishes.
Jobs are not available yet
POST /jobs and GET /jobs/{job_id} are in the contract and are not served. A call
to either returns 404. This page exists so you know the shape they will take and what
to do until then — not to describe something you can use today.
Two things have to change first. No worker consumes the queue, so a job would be accepted and never run. And the job record stores neither the company nor the type, so a job could not describe itself back to you. Until both are fixed, offering the endpoint would sell a request that does nothing.
What to do instead
Most missing data is not missing because nobody asked for it. Check Data coverage first — for a large share of records there is nothing to fetch, because no document was ever filed or the entry has been deleted.
Two things do happen without a job:
Ownership. Asking for
GET /companies/{company_id}/shareholders
starts the work by itself when we hold no shareholder list yet. The response says
availability: processing, and the same request a little later returns the owners. One
call starts at most one extraction, for the company you asked about.
Documents. GET /companies/{company_id}/documents
lists what is already on file. If the document you need is not there, no job will conjure
it — see Data coverage for why.
What it will look like
When jobs ship, this is the shape:
curl -X POST "https://api.registercheck.de/v1/jobs" \
-H "Authorization: Bearer $REGISTERCHECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "refresh_documents", "company_id": "3f1c2a9e-5b7d-4c8a-9e21-6d4f0b8a1c55"}'{
"id": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
"object": "job",
"type": "refresh_documents",
"status": "queued",
"company_id": "3f1c2a9e-5b7d-4c8a-9e21-6d4f0b8a1c55",
"created_at": "2026-03-01T10:00:00Z",
"completed_at": null,
"failure": null
}Three types are defined: refresh_documents, refresh_financial_statements and
refresh_ownership_history.
status is queued, running, succeeded or failed. A register that is temporarily
unavailable reads as running, not failed — the job is still in flight and retrying, so
do not give up on it. A failed job carries a failure with a code you can branch on:
register_unavailable, no_documents_found or internal_error.
Polling will be free (GET /jobs/{job_id} costs no credits), so a sensible interval is
about what the work needs rather than what your budget allows — every 10–30 seconds, with a
backoff that widens as the job runs. Creating a job costs 10 credits.
When it fails
Failure usually means the register had nothing to give — the document was never filed, or
the entry has been deleted. Asking again will not change that. Check whether the company
has an extract at all (address and purpose non-null on the company record) before
assuming the pipeline is at fault.