Poll a session's status
GET /api/verification/:sessionId/status — the polling fallback the shopper's browser uses, the five session states, and why it needs no API key.
Last updated: 2026-09-04
Returns the current state of a verification session. This is the polling fallback for clients that cannot hold an open connection; if you can, prefer the event stream.
GET https://api.eidas-pro.com/api/verification/{sessionId}/status
No API key, and why
This route takes no x-merchant-api-key header, and sending one changes nothing.
It is polled by the shopper's own browser while it waits for the bank or wallet step to finish. A browser cannot hold your merchant key — putting it in that page would publish your key to every visitor — so requiring one here would only push integrators into leaking it. What guards the route instead is the session id: a random UUID held only by the parties to that session, with a per-session rate limit of 120 requests per minute so that one shopper's polling cannot throttle another's.
This is not the endpoint your server should trust
Because it is unauthenticated, anyone holding the session id can read it, and it carries no proof of which merchant the session belongs to. Use it to drive your checkout UI while the shopper waits. Read the verdict your business logic acts on from the authenticated result endpoint, which checks that the session belongs to the key making the request.
Request
curl https://api.eidas-pro.com/api/verification/0f3c1c2b-9a4d-4d1f-8c1a-2b6d5e4f7a90/status
The path segment must be a UUID. Anything else answers 400 with code VALIDATION_ERROR before any lookup happens.
Response
{
"sessionId": "0f3c1c2b-9a4d-4d1f-8c1a-2b6d5e4f7a90",
"verificationType": "age",
"status": "pending"
}
| Field | Notes |
|---|---|
sessionId | Echoes the id you asked for. |
verificationType | age, country, or both — what the session was created for. |
status | One of the five states below. |
verified | Boolean, present once the session has an outcome. |
error | Present only for rejected and expired. Carries code (VERIFICATION_REJECTED or SESSION_EXPIRED) and a message. |
completedAt | Timestamp of the terminal transition, once there is one. |
verifiedAttributes | Declared by the contract for verification paths that produce attributes. The implemented age-only path produces none, so it is absent. |
Session states
status | Meaning | Terminal |
|---|---|---|
pending | Session created; the shopper has not completed the identity step yet. | no |
scanned | The shopper has engaged with the identity step, which is in progress. | no |
verified | The check passed. | yes |
rejected | The check ran and did not pass. | yes |
expired | The session ran out of time. On the broker path that is 15 minutes from creation. | yes |
Stop polling as soon as status is one of the three terminal values. Nothing transitions out of them.
Failures
| Status | code | Cause |
|---|---|---|
400 | VALIDATION_ERROR | The path segment is not a UUID. |
404 | NOT_FOUND | No session with that id — it never existed, or it has aged out of storage. |
429 | RATE_LIMIT_EXCEEDED | 120 requests per minute per session, or 120 failing requests per minute per IP address. |
An unknown session:
{
"error": {
"message": "Verification session not found",
"code": "NOT_FOUND",
"statusCode": 404
}
}
A 404 is the same answer whether the id was never issued or has since expired. Treat it as "this session is over and you did not get a pass" rather than as a transient failure to retry.
A 429 uses the same envelope, with code RATE_LIMIT_EXCEEDED and a top-level retryAfter field alongside it. Back off by the seconds in the Retry-After header. See errors and status codes.