Skip to navigation
Sessions Results

Get Session Results

View as Markdown

Retrieve the decrypted portal records and results of the session.

Key Technical Details:

  • Concurrency Lock (504): Acquires an exclusive database lock on the session. If the lock cannot be acquired within a reasonable time, it returns 504 Gateway Timeout.
  • Rate Limit (429): Access is strictly limited to 1 request every 5 seconds per session to prevent abuse and reduce infrastructure load during heavy decryption and result compiling processes.
  • Data Schema: Returns the decrypted portal records inside the data field (conforming to PublicGlobalPositionSchema) and the list of successfully retrieved features inside retrieved_features.
  • Consent Compliance: Contains the structured consent audit trail in the consent field for compliance tracking.
  • Result Finality (is_closed): Results are final only when the convenience field is_closed is true. While is_closed is false, the results are partial, not final, and subject to changes, modifications, deletions, or new records appearing as background processing continues.

Preconditions:

  • Session Started (412): The flow session must have been opened/started by the customer at least once (generating the started event). If the session has not started yet, the request is rejected with 412 Precondition Failed.
  • Attachment References: If official documents (e.g. PDF reports) were retrieved, they are referenced as IDs within the results payload and must be downloaded via Download Attachments.

This endpoint needs to be executed with an app secret, so should always be used in server side without exposing the secret to customers.

Where each feature lands in data

FeaturePathOfficial document attached
customer_information_readdata.customer.profile—
labor_checkdata.employment.labor_checkWork-life and contribution reports
public_pensionsdata.employment.pensions—
credit_registry_datadata.credit.registryThe Banco de España’s CIRBE report
driver_data, vehicles_datadata.driver.data, data.driver.vehicles—
yearly_individual_taxdata.tax.individual_yearly, one entry per fiscal yearThe filed income-tax return (Modelo 100), when there is one
academic_datadata.academic.higher_education_degrees, data.academic.secondary_education—
properties_datadata.properties.es, one entry per property, every co-owner in owners—

A feature that was asked for and brought nothing back is absent, and retrieved_features says which ones did.

messages — what the session has to say about itself

Beside the records, the results carry a messages list: situations the session detected while it ran. Most sessions detect none and the list is empty; when it is not, each entry is a fact worth knowing about the verification you just received.

A message is not a log line. A situation is reported once, however many times it occurred, so messages is a set of facts about the session rather than a trace of it.

FieldWhat it is
typeflag, warning, error or info — see below
message_idThe stable identifier of the situation, such as profile_identity_mismatch. Automate on this: the wording of message may change without the situation becoming a different one
locationWhere in this results document the message applies, as a loc list
messageA human-readable description, when there is one to add
date_createdWhen the situation was first detected during the session

location is a loc, exactly like a validation error

["data", "driver", "vehicles", 0, "license_plate"] — strings for fields, integers for array positions, walked the same way you already walk the loc of a validation error. An empty list means the message is about the session as a whole rather than about one part of the data.

That is why it is a list and not a dotted string: a results document contains arrays, and data.driver.vehicles.0.license_plate cannot be resolved without guessing whether 0 is a key or an index. With a loc you can put the message on the exact field in your own interface, with no parsing.

What each type means

flag is the one to route

A flag never means something failed on our side. It means the session found something that deserves a decision on yours — a signal about the person or about the data that a clean, successful verification would not normally carry.

Treat flags as an input to your own risk or review rules: a verification can be technically perfect and still be worth a second look. warning and error describe how the reading went; a flag describes what the reading found.

  • flag — something about the end customer or about the data that you may want to act on. Route these.
  • warning — the session did its job, and something about how it did it is worth knowing.
  • error — something did not go as intended during the session. retrieved_features already tells you what did and did not come back; an error adds the reason when there is one to give.
  • info — a note for a person reading the session; nothing to act on.

An example: identities that do not agree

A session may connect more than one administration. When it does, the customer profile is built by merging what each one returned, and the merge compares the identifiers each source reported for the person.

If two sources describe different people, the session raises profile_identity_mismatch as a warning and, beside it, a crossed_identity flag located at ["data", "customer", "profile"] — the merged profile keeps the first source’s identity, and the flag is what tells you the merge was not unanimous.

Why this one cannot happen on this flow — and why the flag is still there

On the Spain Public Administration experience the person authenticates against every administration with the same identity document, which the session fixes when it is created: the customer cannot present one identity to one source and a different one to the next. So on this flow crossed_identity is a guarantee rather than an expectation — it is the check that proves the merge was consistent.

It is described here because it is the clearest shape of what a flag is for: a signal that the data is internally inconsistent in a way no individual source could report. Flows where the customer chooses their own credential per source do not have that guarantee, and this is the field where that would reach you.

What to do with them

  • Store message_id with the verification. It is stable, it is short, and it is what a later question (“how many of our sessions raised this?”) is asked with.
  • Route flags into whatever already decides when a case needs a human. Do not block on them by default: a flag is information, not a verdict.
  • Show message next to the data it is about, using location. That is the whole reason the field is a loc.
  • Do not branch on the wording. message is written for a person and may be rewritten; message_id is the contract.

Authentication

X-APP-SECRETstring
Application Secret

Path parameters

session_idstringRequiredformat: "object-id"
Session ID to fetch

Response

200 OK
FINAL records: the session is finished and nothing more is coming.

is_closedboolean
Indicates if the flow session has been finalized.
status_codeenum
The final execution status code of the session.
cursorenum
The last screen of the widget experience where the user interacted.
connectionsmap from strings to strings
A mapping of internal connection identifiers to the engine references executed.
consentobjectOptional
The structured consent audit trail and accepted document versions signed by the user.
retrieved_featureslist of enumsOptional
The list of features successfully extracted from the official portals during the session.
dataobjectOptional
The retrieved public administration records, conforming to the PublicGlobalPositionSchema.
messageslist of objectsOptionalDefaults to []

What the session has to say about itself and about the data it read, oldest first.

Most sessions say nothing and the list is empty. When it is not, each entry is a situation that was detected while the session ran: an error or a warning about a read, an info note, or a flag — the type raised for you. A flag never means something of ours failed; it means the session found something worth a decision on your side, and location points at the part of this document it is about.

A situation is reported ONCE however many times it occurred, so this list is a set of facts and not a log: automate on message_id, which is stable, and treat message as text for a person.

Errors

404
Not Found Error
412
Precondition Failed Error
422
Unprocessable Entity Error
429
Too Many Requests Error
504
Gateway Timeout Error