Create Session

Initialize a Spain Public Administration flow session to access government portals and retrieve public records.

This endpoint starts the flow lifecycle. Upon successful creation, it returns a session_id and a widget_url. Your frontend application must redirect the customer to the widget_url so they can log in and sign the consent form.

Once the customer completes the widget journey, a webhook notification is delivered (if configured), and the decrypted results can be downloaded using the Get Session Results endpoint.

What the session reads is settings.executions_features, one code per source — ask only for what you need:

So ["credit_registry_data"] reads the CIRBE report alone, and ["labor_check", "credit_registry_data"] both. Left out, the session uses your application’s default features.

A feature goes as its code alone or as an object with its configurations. yearly_individual_tax reads the last three closed fiscal years by default, and up to five with {"code": "yearly_individual_tax", "configurations": {"last_n_years": 5}}.

Each administration the list reaches is one more identification for the person, one after the other: the Social Security first, then the Agencia Tributaria, then the Carpeta Ciudadana (which serves academic_data and properties_data). Ask for what you will use.

settings.sandbox is required: true runs against the sandbox, with no real administration behind it; false is production.

Why a session is refused:

• 400 — the return URL is not one of your application’s.
• 403 — a production session from an application that is not in production, or without the capability it needs (insufficient_capabilities@product:es_public_administration); a sandbox session needs none.
• 409 — a session with that customer_id is already open.

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