Skip to main content

The Trip Flow

This page explains the overall structure and concepts behind the Fluxir trip flow. This trip flow provides a robust and flexible model for creating service applications around travel. By combining traveler data, contextual requirements, and document processing, the workflow simplifies complex regulatory processes and helps users build complete and valid applications.

Key Concepts

Refer to the Fluxir Concepts page to understand the foundational elements that structure this workflow.

What Is the Trip Flow?​

The trip flow in Fluxir represents the lifecycle of requesting and applying for a travel-related service (such as a visa or travel authorization). The process involves gathering required documents, selecting a traveler, validating identity, and submitting a finalized application.

This flow ensures that:

  • All service-specific requirements are collected dynamically based on the trip context.
  • The correct identity and supporting documents are provided.
  • Data merging and validation are performed before final submission.

Call Sequence​

The following diagram summarizes the order of API calls in a typical trip flow. Each call is described in detail in the stages below.

High-Level Stages​

The trip flow is composed of several stages, each with a specific purpose. Each step links to the API operation that performs it.

1. Service Discovery and Trip Initialization​

  • Fetch Service Intents: Determine which travel services are available for the trip context (origin, destination, and dates) using Get Service Intents. Each service intent is identified by its serviceIntentKey and references the documentSchemeVersionId that describes its required data.
  • Get Document Schema: Retrieve the sections and fields required by the selected service intent using Get Documents Scheme with the intent's documentSchemeVersionId. The schema depends on the selected service, not on the traveler.
  • Create Trip: Define the trip (origin, destination, and dates) that the service applications will belong to using Create Trip.
  • Get Trip Context: Retrieve trip-level context values, such as trip dates and countries, that can prefill application fields. Use Get Trip Context by ID for an existing trip, or Get Trip Context to compute it from origin, destination, and dates.

2. Traveler Selection and Application Creation​

  • Select or Create a Traveler: Choose an existing traveler using Get Persons, or create one using Create Person or Create Person from Passport.
  • Get Traveler Context: Retrieve traveler-level context values, such as profile and identity document data, using Get Travel Service Context. Before the application exists, pass personId, schemeVersionId, and originationCode; afterward, pass serviceApplicationId.
  • Create a Service Application: Create a Draft application using Create Travel Service Application. The request links the traveler and the trip through personId and tripId; there is no separate call to assign a traveler to a trip. If an application already exists for the same trip, traveler, and service type, the existing application is returned.

3. Prefill from Context​

  • Identify Fields to Merge: Compare the trip and traveler context values with the current application values for the fields defined in the document schema. This comparison is performed by the client; the created application is not prefilled automatically.
  • Confirm Merged Fields: Let the user confirm values that would replace existing, different values.
  • Save Current Application: Persist the merged values using Update Travel Service Application. The application remains in Draft.

4. Identity Document Handling​

If the document schema requires an identity document, such as a passport, this subprocess is triggered:

  • Recognize Identity Document: Extract candidate data from the uploaded image using Passport Recognition.
  • Upload File to Storage: Store the file as an attachment using Upload Document Item Attachment. The returned attachment id becomes the value of the corresponding application field.
  • Confirm Recognized Values: Recognition output is candidate data. Let the user review and confirm it before it is stored on the traveler profile.
  • Create or Update Identity Document: Store the confirmed data on the traveler using Create Identity Document or Update Identity Document.
  • Refresh Traveler Context: Retrieve the updated traveler context using Get Travel Service Context with serviceApplicationId.
  • Identify, Confirm, and Merge Fields: Repeat the merge from stage 3 with the refreshed context.
  • Save Current Application: Persist the merged values using Update Travel Service Application.

5. Final Application Composition​

  • Collect Remaining Fields: Walk through the fields defined in the document schema that are still empty, and handle each according to its item type (text, date, enum, country, file, and so on).
  • Upload File to Storage (file fields only): Upload the file using Upload Document Item Attachment and use the returned attachment id as the field value.
  • Save Current Application: Persist the updates using Update Travel Service Application. The application can be saved incrementally while it remains in Draft.
Saving Updates Traveler Data

Saving an application validates the submitted values. Values of fields that are bound to the traveler profile may also update the traveler's stored data, so they can be reused in future applications.

6. Submission and Payment​

  • Check Billing Readiness: Before any paid submission, check the tenant's readiness as described in the API Billing Readiness guide.
  • Submit the Application: Change the application state from Draft to ReadyForReview or ReadyForPayment using Update Travel Service Application. If validation fails, the request returns validation errors and the application stays in Draft, so the user can correct the reported fields and submit again.
  • Complete Checkout (portal payment flow): When payment is required through interactive checkout, start it using Get Trip Checkout and complete it using Finalize Trip Checkout.

Why It Matters​

The Fluxir trip flow is designed to:

  • Reduce redundant data entry by merging trip and traveler context into the application.
  • Keep recognized identity data under user control through explicit confirmation.
  • Handle complex document requirements in a modular, extensible way.
  • Allow applications to be saved incrementally, supporting multi-step or asynchronous input collection.

What's Next?​

Now that you are familiar with the concepts of creating a trip, refer to the Create a Trip API Guide to see how to execute this process with the Fluxir API.