Sessions

A Flow session is a single execution instance of a Flow by a user or customer. It tracks progress through configured steps, collected input, generated artifacts, and the final session result.

Terminology

• Use Flow session (or simply session) as the canonical term.
• Avoid wording that implies session ownership by operators. Operators manage and review sessions, but sessions are instances of flows.

Lifecycle

1. PENDING: Session created, waiting for user input.
2. PROCESSING: User has submitted data and checks are running.
3. COMPLETED: The flow finished and a result is available.
4. EXPIRED: User did not complete within the configured timeout.

Creating a Session

Currently, Flow sessions are initiated in two ways:

1. Dashboard: An authorized operator generates a unique link for a customer to complete checks.
2. Transactions (KYT): A transaction rule can trigger a step-up verification session when additional evidence is needed.

Direct public Flow-session creation is not currently documented as a client-credential API. If your integration needs server-side session creation, confirm the enabled contract with your PredictaID administrator.

Public Session Access

The frontend application (or your mobile app) accesses the session configuration via:

Endpoint: GET /kyc-sessions/:id/public

Returns:

• steps: The UI steps to render.
• flowName: Name of the flow.
• branding: Your company's branding (Logo, Colors).

Treat the session ID and hosted link as sensitive. Anyone with the valid public session link can interact with that session.

Completing a Session

When the user finishes the steps, the frontend submits the data:

Endpoint: POST /kyc-sessions/:id/complete

Payload:

{
  "userData": {
    "name": "User Name",
    "cpf": "123.456.789-00",
    "selfie_url": "..."
  }
}

Uploading Artifacts

Hosted and embedded experiences can upload artifacts collected during the Flow session, such as document images or proof files.

Endpoint: POST /kyc-sessions/:id/upload

Use multipart/form-data with a file field.

Uploaded artifacts should be linked to the dossier by the platform or by operator actions when a link cannot be resolved automatically.

Webhooks

When a session reaches a terminal state, PredictaID can send a webhook to your configured endpoint.

Event: session.completed

{
  "type": "session.completed",
  "data": {
    "sessionId": "sess_123",
    "status": "COMPLETED",
    "customerId": "cust_abc",
    "riskScore": 10
  }
}

See Webhook Events Reference for the canonical event names.