Skip to main content
POST
Start a job

Start a realtime job

Fetch fresh data from the Handelsregister without waiting for it. The request returns at once with a pending job, and OpenRegister fetches the data in the background. Use a job instead of realtime=true when your client cannot keep a request open while the Handelsregister answers. Cost: 20 credits for company and owners jobs, 10 credits for document jobs, charged when the job completes. Failed jobs are free.

Job types

Following a job

Follow a job either way, or both:
  1. Polling: call Get Job with the returned id until status is completed or failed. A completed job carries its result in results.
  2. Webhook: configure a webhook endpoint in your OpenRegister dashboard. When the job finishes, OpenRegister sends a job.completed or job.failed webhook to it. The webhook carries no result; read results with Get Job.
Webhooks are delivered and signed the same way as monitor webhooks, see Receiving Webhooks and Verifying Webhook Signatures.
If your endpoint subscribes to selected event types only, add job.completed and job.failed to receive job webhooks.

Webhook payload

job.completed and job.failed share one payload.
string
required
Event type identifier: job.completed or job.failed.
string
required
Job ID, as returned by POST /v1/jobs.
string
required
Job type: company, owners or document.
string
required
Company register ID the job refreshed (e.g. DE-HRB-F1103-267645).
string | null
required
Document category of a document job; null for company and owners jobs.
string
required
Final job status: completed or failed.
string | null
required
Why the job failed, see failure reasons; null for completed jobs.
string
required
When the job finished (ISO 8601 / RFC 3339).

Error cases

Notes

  • document_category is required for document jobs and not allowed for other types.
  • For company and owners jobs, company_id in the response is the company’s latest register ID. It differs from the requested one when the company moved to another register.

Authorizations

Authorization
string
header
required

API Key Authentication Provide your API key as a Bearer token in the Authorization header.

Rejected keys return a JSON body {"message": "..."} naming the reason:

  • 401 API key is missing, API key is invalid, API key is disabled or API key has expired
  • 429 API key rate limit exceeded or API key usage limit exceeded

Body

application/json
type
enum<string>
required
Available options:
company,
owners,
document
company_id
string
required

Unique company identifier. Example: DE-HRB-F1103-267645

document_category
enum<string>
Available options:
current_printout,
chronological_printout,
historical_printout,
structured_information,
shareholder_list,
articles_of_association

Response

The job was accepted and is pending

id
string<uuid>
required

Unique job identifier. Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

type
enum<string>
required
Available options:
company,
owners,
document
company_id
string
required

Company the job refreshes. For company and owners jobs this is the company's latest register ID, which differs from the requested one when the company moved to another register. Example: DE-HRB-F1103-267645

document_category
enum<string> | null
required
Available options:
current_printout,
chronological_printout,
historical_printout,
structured_information,
shareholder_list,
articles_of_association
status
enum<string>
required
Available options:
pending,
completed,
failed
reason
enum<string> | null
required

Why a failed job failed:

  • not_available: the register holds no such document for this company.
  • timeout: the Handelsregister did not answer in time; try again later.
  • internal_error: any other failure.
Available options:
not_available,
timeout,
internal_error
results
object | null
required

What a completed job produced, until expires_at. Null while the job is pending, when it failed, and after the results expired.

expires_at
string<date-time> | null
required

Until when a completed job returns results, 12 hours after it finished.

created_at
string<date-time>
required
finished_at
string<date-time> | null
required