How to check up to 10,000 Norwegian companies in one async job

GET /api/v1/public/company-status answers up to 100 org numbers in one call. For a larger list, submit it as one bulk verification job and read the results as they arrive. Each item is answered with the same row the synchronous call serves.

Step 1 — Submit the jobCopy Anchor Link

curl -X POST "https://www.apier.no/api/v1/company/bulk-jobs" \
  -H "Authorization: Bearer $APIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"org_numbers":["999999999"]}'

The body holds exactly one field, org_numbers: 1 to 10,000 org numbers of exactly 9 digits. Repeats are removed and the first occurrence keeps its place, so data.duplicates_removed says how many were dropped and the items keep your order.

The answer is 202 with the job, its status (queued) and the URL to read it from, in both the Location header and data.results_url. Send an Idempotency-Key: a retried submission with the same key returns the same 202 and never creates a second job. One key holds at most 3 open jobs (queued, running or paused); a fourth submission answers 429 RATE_LIMITED with a Retry-After header, and is accepted once one of the open jobs has completed.

Step 2 — Read the resultsCopy Anchor Link

curl -H "Authorization: Bearer $APIER_API_KEY" \
  "https://www.apier.no/api/v1/company/bulk-jobs/$JOB_ID?limit=100"

A scheduled processor answers the items in submission order, every few minutes. The answer carries the job's status (queued, running, paused or completed) and counts, and one page of items sorted by seq. Each item has:

• status: pending, answered, not_found or failed;
• check_status, the shared status: verified, missing, unavailable or not_checked;
• charged: whether the item was billed;
• result: for an answered item, the company-status row for that org number; null otherwise.

Step 3 — Page through the itemsCopy Anchor Link

Pass data.page.next_after_seq as after_seq to read the next page. limit is 1 to 1000 and 100 when you leave it out. next_after_seq is null on the last page. Poll the job until status is completed.

Get a webhook when a job completesCopy Anchor Link

Instead of polling, create an event subscription with POST /api/v1/subscriptions and the filter {"events": ["bulk_job.completed"]} (a key with the subscribe:webhooks scope). When the last item of a job submitted by any key of your account gets an outcome, Apier POSTs one bulk_job.completed delivery to your URL. The body carries the job (event, bulk_job with its counts and bulk_job.results_url), not its items; read them from results_url. It is signed, retried and auto-disabled exactly like a change delivery. A subscription that does not name the event never receives it, and an event subscription never receives change rows.

Rules and billingCopy Anchor Link

• Submitting a job is not billed. Each answered item is billed as one company read, once: the charge is keyed on the job and the org number, so a retry never charges twice. An org number not found in the register is never billed. See pricing.
• When the wallet runs out or a spend cap is reached, the job pauses (paused_reason says which) and never goes negative. It resumes by itself once there is credit or cap room again.
• If Brønnøysund cannot answer an item, it is retried on later runs; an item still unanswered a day after the job was created is marked failed and is not billed.
• Any key or sub-key of the account that submitted the job can read it. Another account's job answers 404 NOT_FOUND, like an unknown id.
• Both endpoints need an API key with the read:brreg scope.