Autorekisteri machine API v1.0.0

Integration guide

For developers connecting a system to Autorekisteri's vehicle-registry lookups. The formal contract is openapi.json (OpenAPI 3.1); this guide explains how to use it.

1. Get credentials

An administrator of your organisation creates an API client in https://business.autorekisteri.fi → Tili → Rajapinta-asiakkaat and chooses which lookup tiers it may use. The portal shows the client ID, client secret, token URL and API URL once. Store the secret in your secret manager; if it is lost, create a new client and revoke the old one. Your organisation must first be enabled for API access by Autorekisteri.

Use one client per system, so that one can be revoked without stopping the others. Revocation takes effect immediately, including for tokens already issued: every request with the client's tokens then gets 401 CLIENT_REVOKED.

A client can be revoked by an administrator of your organisation, or by Autorekisteri.fi staff (for example when a credential is reported leaked). Your organisation's administrators are e-mailed whenever a client is created or revoked, with the client's name, its tiers, who made the change and when; the mail never contains a client ID or secret. The portal also flags a client nobody has used for 90 days, so that a forgotten credential can be revoked.

2. Get an access token

OAuth 2.0 client credentials, HTTP Basic authentication with the client ID and secret:

curl -s -X POST "$TOKEN_URL" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials'

{ "access_token": "eyJ…", "expires_in": 3600, "token_type": "Bearer" }

Without a scope parameter the token carries every scope your client was granted. The token is valid for 60 minutes. Cache it and reuse it until shortly before expires_in; do not request a new token for every lookup.

Scopes, where {api} is the API URL from the table above:

Any lookup.* scope also allows reading back your own lookups and their PDFs.

3. Look up a vehicle

curl -s -X POST "$API/v1/lookups" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-4711' \
  -d '{"registrationNumber":"ABC-123","vehicleType":"auto","tier":"historia"}'

• registrationNumber: a Finnish plate (ABC-123, 123-ABC, CD-1234, C-12345). Case and spaces do not matter and a missing hyphen is inserted (abc123 is ABC-123); the plate in every response is the normalised one. The plate's shape must be one the vehicle type has in the register (L a letter, Å, Ä and Ö included; N a digit):

  vehicleType	shapes
  auto	LL-N … LL-NNNN, LLL-N … LLL-NNN
  perakarry	LLL-N … LLL-NNN, LL-NNNN
  moottoripyora	LL-N … LL-NNN, NN-LLL
  mopo	NN-LLL, LL-NN, LL-NNN
  moottorityokone	N-LL … NNN-LL, N-LLL … NNN-LLL
  maastoajoneuvo	NNN-LL, NNN-LLL

  CD-N … CD-NNNN and C-N … C-NNNNN are accepted for every type. Anything else is refused with 400 INVALID_REGISTRATION_NUMBER before a query is made or billed; when the plate is a valid shape for some other type, the problem also carries vehicleType and expectedShapes (the list above for that type). Check both the registration number and the vehicle type.

• vehicleType: auto, moottoripyora, moottorityokone, maastoajoneuvo, perakarry (trailers and caravans) or mopo.

• tier: perus, laaja or historia.

The call is synchronous and usually answers within a few seconds; allow up to 30 seconds before treating it as timed out.

{
  "lookupId": "k3q7…",
  "registrationNumber": "ABC-123",
  "vehicleType": "auto",
  "tier": "historia",
  "createdAt": "2026-10-16T10:15:00.000Z",
  "outcome": "ok",
  "traficomErrorCode": null,
  "resultExpiresAt": "2026-10-17T10:15:00.000Z",
  "report": { "sections": [ … ], "owners": [ … ], "notices": [ … ], "unknownCodes": [] }
}

outcome — check this before reading report

All three are HTTP 200, because the query completed and was recorded.

The report

report.sections[] contains { key, title, fields[] }, and each field is { key, label, value }. Program against key. title and label are Finnish display text, and value is a display string ("13.09.2010", "1 598 cm3") or null when the register has no value. Every section and field key is listed in openapi.json. Repeated entries have numbered keys (katsastus.1, katsastus.2, …).

report.owners[] follows the disclosure rules filed with Traficom: a private person's name or address may be withheld, and is then replaced by fixed wording. Each owner's group says whether it is a current owner (owner), a current holder (holder) or an ended relationship (previous, historia only), the grouping Traficom's own report uses. report.notices[] holds restrictions and warnings ("Huom. …"). A section that has nothing to show and says so carries emptyState, the sentence to print in its place.

Retention

The report is kept for 24 hours (resultExpiresAt), then deleted. This is a contractual maximum, so plan on it. Your own copy is subject to your agreement with Traficom.

4. Retries and Idempotency-Key

Each lookup is a billed government query. If a request times out you cannot tell whether it reached Traficom, so send an Idempotency-Key on every lookup, unique to your business transaction (A-Z a-z 0-9 . _ : -, at most 128 characters). Repeat the request with the same key and body:

Keys are remembered for 24 hours.

5. Reading results back, PDF and usage

• GET /v1/lookups/{lookupId} returns the same object for 24 hours, then 410 RESULT_EXPIRED.
• GET /v1/lookups/{lookupId}/report.pdf with Accept: application/pdf returns the report as a PDF.
• GET /v1/usage?month=2026-10 (scope usage.read) returns your client's lookups and per-tier counts for invoice reconciliation.

A client can read only lookups it made itself.

6. Errors

Errors are application/problem+json (RFC 9457):

{ "type": "about:blank", "title": "Tier not permitted for this client", "status": 403, "code": "TIER_NOT_PERMITTED" }

Switch on code; title and detail may change. Errors raised by the API gateway itself (missing or invalid token, missing scope, malformed body, unknown path, throttling, firewall) carry the same body with Content-Type: application/json; parse the body, not the header.

402 Payment Required

Your organisation's monthly lookups are charged to its payment card on the 1st of the following month. If that charge does not go through, the organisation's admins are warned in the business portal, and after a few days' grace (3 by default) new lookups are paused until the month is paid:

{ "type": "https://api.business.autorekisteri.fi/docs#payment-required", "title": "Payment required", "status": 402, "code": "PAYMENT_REQUIRED", "detail": "…" }

Only POST /v1/lookups stops; reading earlier lookups, reports and usage keeps working. Nothing is sent to Traficom and nothing is billed. An organisation admin updates the card in the business portal (Laskutus), and lookups resume as soon as the payment succeeds, which a new card triggers at once. Retrying the request does not help until then; treat it as a state of your account, not of the request. The type is this page's anchor, on the host you call.

7. Rate limits

Lookups are limited per client, per organisation and service-wide over rolling windows; exceeding a limit answers 429 with Retry-After. Ask Autorekisteri if your expected volume needs higher limits. Fetching tokens is limited separately by the token service, which is another reason to cache them.

8. Moving from the old API

The old endpoint (index.php?option=com_autorekisteripayment&view=api) takes api_pub plus an MD5 auth in the body and answers with Finnish-keyed JSON. This API replaces all of that:

The two endpoints run in parallel during an agreed transition period.

API reference

Servers

Authentication

OAuth 2.0 client credentials. {resourceServer} is the API's own base URL (https://api.business.autorekisteri.fi or the test one). The token URL is shown with your client credentials in the portal.

Schemas