> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://infonite.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://infonite.dev/_mcp/server.

# Create Session

POST https://widgets.infonite.tech/api/flows/es-public-administration/v1/manager/init
Content-Type: application/json

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](api:GET/es-public-administration/v1/manager/{session_id}/results) endpoint.

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


Reference: https://infonite.dev/api-reference/spain-public-administration/spain-public-administration-api/sessions-management/flows-es-public-administration-v-1-session-create

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: es-public-administration-v1-0-0-openapi
  version: 1.0.0
paths:
  /es-public-administration/v1/manager/init:
    post:
      operationId: flows:es-public-administration:v1:session-create
      summary: Create Session
      description: >
        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](api:GET/es-public-administration/v1/manager/{session_id}/results)
        endpoint.


        > This endpoint needs to be executed with an app secret, so should
        always be used in server side without exposing the secret to customers.
      tags:
        - sessionsManagement
      parameters:
        - name: X-APP-SECRET
          in: header
          description: Application Secret
          required: true
          schema:
            type: string
      responses:
        '200':
          description: '**200 OK**<br>Flow Session created successfully'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Acceptance'
        '409':
          description: '**409 Conflict**<br>Flow Session already exists'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/catgrid_flows__flows__es_public_administration__v1__schemas__manager__FlowStateSchema__Create
servers:
  - url: https://widgets.infonite.tech/api/flows
    description: Production Server
  - url: https://widgets-dev.infonite.tech/api/flows
    description: Development Server
  - url: /api/flows
    description: Local Server
components:
  schemas:
    FixedParameters:
      type: object
      properties:
        user_identification:
          type: string
          format: spanish-NIF
          description: >-
            Optional Spanish NIF/NIE to enforce during authentication. The
            widget will restrict access to this user.
        user_email:
          type: string
          format: email
          description: >-
            Optional email address for the customer. This email will be used as
            a fallback when no email is found 

            in the user's public administration profile. For example, when
            downloading CIRBE credit registry reports, 

            the system requires an email for sending notifications. The system
            will first attempt to use the email 

            from the user's public administration profile, but if none exists,
            it will use the email you provide here.


            <Note>

            The email is only used for notification purposes, not for data
            access.

            </Note>
      description: >-
        Predefined and fixed parameters to lock for the public administration
        engines.


        <Warning>

        All personal data provided in this section must have the proper consent
        of the user. 

        INFONITE assumes the client has obtained the necessary consent to use
        this data.

        </Warning>
      title: FixedParameters
    FlowHooksExtraDataType:
      type: object
      additionalProperties:
        type: string
      description: >-
        Extra data to be included in the hooks. This data will be returned in
        the webhook as part of the URL as query parameters. This can be useful
        to include dynamic data in the webhook.

        There are some template variables that can be used:

        - `{app_id}`: Your app ID

        - `{customer_id}`: The customer ID

        - `{session_id}`: The Session ID

        - `{parameters_id}`: The unique credentials ID, this identifier is
        computed by the engine based on the fixed part of the credentials  (e.g.
        the username)

        - `{producer}`: The producer of the event

        - `{event}`: The event that triggered the hook

        - `{status_code}`: The status of the flow at the moment of the event

        For example, passing:

        ```json

        {
          "custom_param": "customValue",
          "current_event": "{event}",
          "status": "{status_code}",
          "id": "{session_id}"
        }

        ```

        Will result in the following URL:

        `https://your.url.com/your/path?custom_param=customValue&current_event=ended&status=COMPLETED&id=67d7d9b72eb0693e7da47a0e`


        > **Note:** This data is not encrypted and should not contain sensitive
        information.
      title: FlowHooksExtraDataType
    CreditRegistryDataType:
      type: string
      enum:
        - credit_registry_data:es_cirbe_detailed
        - credit_registry_data:es_cirbe_aggregated
      title: CreditRegistryDataType
    catgrid_forms__engines__features__public__credit_registry_data__FeatureConfigurations:
      type: object
      properties:
        preferred_type:
          $ref: '#/components/schemas/CreditRegistryDataType'
          description: Preferred credit registry report type to retrieve
      title: >-
        catgrid_forms__engines__features__public__credit_registry_data__FeatureConfigurations
    IFeatureConfigurations:
      type: object
      properties: {}
      description: This feature does not require any configuration
      title: IFeatureConfigurations
    catgrid_forms__engines__features__public__driver_data__FeatureConfigurations:
      type: object
      properties:
        read_point_movements:
          type: boolean
          default: false
      title: >-
        catgrid_forms__engines__features__public__driver_data__FeatureConfigurations
    catgrid_forms__engines__features__public__labor_check__FeatureConfigurations:
      type: object
      properties:
        from_date:
          type: string
          format: date
          default: 12 months ago
          description: The date from which the contribution history will be retrieved
        work_life_report:
          type: boolean
          default: true
          description: Whether to read the work life report.
        contribution_base_report:
          type: boolean
          default: false
          description: Whether to read the contribution base report.
      title: >-
        catgrid_forms__engines__features__public__labor_check__FeatureConfigurations
    catgrid_forms__engines__features__public__vehicles_data__FeatureConfigurations:
      type: object
      properties:
        simple_vehicle_report:
          type: boolean
          default: false
      title: >-
        catgrid_forms__engines__features__public__vehicles_data__FeatureConfigurations
    CatgridFlowsFlowsEsPublicAdministrationV1SchemasManagerFlowSettingsSchemaCreateExecutionsFeaturesItems:
      oneOf:
        - type: object
          properties:
            code:
              type: string
              enum:
                - credit_registry_data
              description: 'Discriminator value: credit_registry_data'
            configurations:
              $ref: >-
                #/components/schemas/catgrid_forms__engines__features__public__credit_registry_data__FeatureConfigurations
          required:
            - code
          description: >-
            Feature that retrieves credit registry risk reports from public
            administrations/central credit registers.
        - type: object
          properties:
            code:
              type: string
              enum:
                - customer_information_read
              description: 'Discriminator value: customer_information_read'
            configurations:
              $ref: '#/components/schemas/IFeatureConfigurations'
          required:
            - code
          description: >-
            Extracts the profile information of the user from the connected
            source. 


            For example, in banking contexts, this feature retrieves available
            information of the logged-in user,

            such as emails, document numbers, phone numbers, addresses, and
            other profile details.
        - type: object
          properties:
            code:
              type: string
              enum:
                - driver_data
              description: 'Discriminator value: driver_data'
            configurations:
              $ref: >-
                #/components/schemas/catgrid_forms__engines__features__public__driver_data__FeatureConfigurations
          required:
            - code
          description: Feature that retrieves the driver data from public administrations.
        - type: object
          properties:
            code:
              type: string
              enum:
                - labor_check
              description: 'Discriminator value: labor_check'
            configurations:
              $ref: >-
                #/components/schemas/catgrid_forms__engines__features__public__labor_check__FeatureConfigurations
          required:
            - code
          description: >-
            Feature that extracts labor check information from public services.


            When requested from engines like TGSS (Spain), it will fetch and
            parse:

            - Labor history ("Vida Laboral") PDF document

            - Monthly social security contributions

            - Employment history with companies

            - Other labor-related information
        - type: object
          properties:
            code:
              type: string
              enum:
                - public_pensions
              description: 'Discriminator value: public_pensions'
            configurations:
              $ref: '#/components/schemas/IFeatureConfigurations'
          required:
            - code
          description: >-
            Feature that retrieves public pension information from government
            services.


            Fetches details about:

            - Retirement pensions and benefits 

            - Widow/survivor pensions

            - Disability/incapacity benefits

            - Other government social assistance

            - Pension type, category, and amounts
        - type: object
          properties:
            code:
              type: string
              enum:
                - vehicles_data
              description: 'Discriminator value: vehicles_data'
            configurations:
              $ref: >-
                #/components/schemas/catgrid_forms__engines__features__public__vehicles_data__FeatureConfigurations
          required:
            - code
          description: Feature that retrieves the vehicle data from public administrations.
      discriminator:
        propertyName: code
      title: >-
        CatgridFlowsFlowsEsPublicAdministrationV1SchemasManagerFlowSettingsSchemaCreateExecutionsFeaturesItems
    CatgridFlowsFlowsEsPublicAdministrationV1SchemasManagerFlowSettingsSchemaCreateCompletionMode:
      type: string
      enum:
        - do_nothing
        - redirect
        - redirect_blank
        - close_tab
      description: The redirection mode to trigger when the user exits the widget.
      title: >-
        CatgridFlowsFlowsEsPublicAdministrationV1SchemasManagerFlowSettingsSchemaCreateCompletionMode
    FlowRedirectExtraDataType:
      type: object
      additionalProperties:
        type: string
      description: >-
        Extra data to be included in the redirect URL. This data will be added
        to the the url as query parameters. This can be useful to include
        dynamic data in the webhook.

        There are some template variables that can be used in the URL:

        - `{app_id}`: Your app ID

        - `{customer_id}`: The customer ID

        - `{session_id}`: The Session ID

        - `{status_code}`: The final status code of the session

        For example, passing:

        ```json

        {
          "custom_param": "customValue",
          "status": "{status_code}",
          "id": "{session_id}"
        }

        ```

        Will result in the following URL:

        `https://your.url.com/your/path?custom_param=customValue&status=COMPLETED&id=67d7d9b72eb0693e7da47a0e`


        > **Note:** This data is not encrypted and should not contain sensitive
        information.
      title: FlowRedirectExtraDataType
    catgrid_flows__flows__es_public_administration__v1__schemas__manager__FlowSettingsSchema__Create:
      type: object
      properties:
        sandbox:
          type: boolean
          description: Set to true to initialize the session in sandbox/test mode.
        aes_key:
          type: string
          format: base64
          description: >-
            Optional 32-byte base64-encoded AES key. If provided, the final
            webhook payload will contain the results encrypted with this key.


            > If the `aes_key` is not specified, the webhook callbacks will not
            deliver the extracted data payload (it will be omitted/null), and
            you must retrieve the results manually using the session API.


            > **Security Best Practice**: Generate a unique, cryptographically
            secure random 32-byte key dynamically for each session. Never reuse
            AES keys across different sessions to ensure proper cryptographic
            isolation.
        hooks_extra_data:
          $ref: '#/components/schemas/FlowHooksExtraDataType'
        executions_features:
          type: array
          items:
            $ref: >-
              #/components/schemas/CatgridFlowsFlowsEsPublicAdministrationV1SchemasManagerFlowSettingsSchemaCreateExecutionsFeaturesItems
          description: >-
            The list of public administration features to retrieve (e.g. life
            employment certificate, vehicle details, etc.).
        completion_mode:
          $ref: >-
            #/components/schemas/CatgridFlowsFlowsEsPublicAdministrationV1SchemasManagerFlowSettingsSchemaCreateCompletionMode
          description: The redirection mode to trigger when the user exits the widget.
        completion_url:
          type: string
          description: >-
            The target URL where the user is redirected when they complete or
            exit the widget.
        completion_extra_data:
          $ref: '#/components/schemas/FlowRedirectExtraDataType'
      required:
        - sandbox
      description: Initialization settings payload for the session.
      title: >-
        catgrid_flows__flows__es_public_administration__v1__schemas__manager__FlowSettingsSchema__Create
    catgrid_flows__flows__es_public_administration__v1__schemas__manager__FlowStateSchema__Create:
      type: object
      properties:
        customer_id:
          type: string
          description: >-
            The external identifier of the customer in your system. Used for
            auditing and tracking.
        date_limit:
          type: string
          format: datetime
          description: >-
            Custom expiration deadline for this session. After this timestamp,
            the widget cannot be opened.
        fixed_parameters:
          $ref: '#/components/schemas/FixedParameters'
          description: >-
            Restricted credentials/parameters to enforce during user login in
            the widget.
        settings:
          $ref: >-
            #/components/schemas/catgrid_flows__flows__es_public_administration__v1__schemas__manager__FlowSettingsSchema__Create
          description: >-
            Custom session settings containing requested features, redirection
            URLs, and webhook extra parameters.
      required:
        - customer_id
        - settings
      title: >-
        catgrid_flows__flows__es_public_administration__v1__schemas__manager__FlowStateSchema__Create
    Acceptance:
      type: object
      properties:
        session_id:
          type: string
          format: ObjectId
          description: The unique database identifier of the created flow session.
        widget_url:
          type: string
          description: >-
            The secure redirection URL where the customer should be sent to open
            the widget.
        session_token:
          type: string
          description: >-
            Temporary security token scoped for the widget to interact with
            backend services during the session.
      required:
        - session_id
        - widget_url
        - session_token
      title: Acceptance
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error message
      required:
        - detail
      description: Error response details
      title: ErrorResponse
    ValidationErrorLocItems:
      oneOf:
        - type: string
        - type: integer
      title: ValidationErrorLocItems
    ValidationErrorCtx:
      type: object
      properties: {}
      title: ValidationErrorCtx
    ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorLocItems'
        msg:
          type: string
        type:
          type: string
        input:
          description: Any type
        ctx:
          $ref: '#/components/schemas/ValidationErrorCtx'
      required:
        - loc
        - msg
        - type
      title: ValidationError
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      title: HTTPValidationError
  securitySchemes:
    Application-Secret:
      type: apiKey
      in: header
      name: X-APP-SECRET
      description: Application Secret

```

## Examples



**Request**

```json
{
  "customer_id": "cust_esp_202406",
  "settings": {
    "sandbox": true
  }
}
```

**Response**

```json
{
  "session_id": "644599da47847b79c03cc94f",
  "widget_url": "https://widgets.infonite.tech/session/644599da47847b79c03cc94f/start",
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI2NDQ1OTlkYTQ3ODQ3Yjc5YzAzY2M5NGYiLCJpYXQiOjE2ODU2MjQwMDB9.4f3b2a1c9d8e7f6a5b4c3d2e1f0a9b8c"
}
```

**SDK Code**

```python
import requests

url = "https://widgets.infonite.tech/api/flows/es-public-administration/v1/manager/init"

payload = {
    "customer_id": "cust_esp_202406",
    "settings": { "sandbox": True }
}
headers = {
    "X-APP-SECRET": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://widgets.infonite.tech/api/flows/es-public-administration/v1/manager/init';
const options = {
  method: 'POST',
  headers: {'X-APP-SECRET': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"customer_id":"cust_esp_202406","settings":{"sandbox":true}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://widgets.infonite.tech/api/flows/es-public-administration/v1/manager/init"

	payload := strings.NewReader("{\n  \"customer_id\": \"cust_esp_202406\",\n  \"settings\": {\n    \"sandbox\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-APP-SECRET", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://widgets.infonite.tech/api/flows/es-public-administration/v1/manager/init")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-APP-SECRET"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer_id\": \"cust_esp_202406\",\n  \"settings\": {\n    \"sandbox\": true\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://widgets.infonite.tech/api/flows/es-public-administration/v1/manager/init")
  .header("X-APP-SECRET", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer_id\": \"cust_esp_202406\",\n  \"settings\": {\n    \"sandbox\": true\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://widgets.infonite.tech/api/flows/es-public-administration/v1/manager/init', [
  'body' => '{
  "customer_id": "cust_esp_202406",
  "settings": {
    "sandbox": true
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-APP-SECRET' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://widgets.infonite.tech/api/flows/es-public-administration/v1/manager/init");
var request = new RestRequest(Method.POST);
request.AddHeader("X-APP-SECRET", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"customer_id\": \"cust_esp_202406\",\n  \"settings\": {\n    \"sandbox\": true\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-APP-SECRET": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "customer_id": "cust_esp_202406",
  "settings": ["sandbox": true]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://widgets.infonite.tech/api/flows/es-public-administration/v1/manager/init")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```