---
title: "Starting an Application"
description: "Learn how the embedded application lifecycle works in the Embedded Journey"
url: "https://docs.wayflyer.com/embedded-journey-v5-overview/using-the-sdk/started-an-embedded-application"
image: "https://docs.wayflyer.com/_og/d/c_Ocean.takumi,title_Starting+an+Application,description_Learn+how+the+embedded+application+lifecycle+works+in+the+Embedded+Journey,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMyMzIzMmQifX19,p_Ii9lbWJlZGRlZC1qb3VybmV5LXY1LW92ZXJ2aWV3L3VzaW5nLXRoZS1zZGsvc3RhcnRlZC1hbi1lbWJlZGRlZC1hcHBsaWNhdGlvbiI,s_Jkh-kVEn0KY_dnAV.png"
---

## Starting an Application

How users apply for financing through the Embedded Journey, from opening the panel to handover.

## [Overview](#overview)

In the Embedded Journey, the initial application steps take place inside your platform. When a user clicks the CTA banner, an embedded panel opens and guides them through a series of steps to collect the information Wayflyer needs to begin processing their application. Once complete, the user is handed over to Wayflyer to finalise (bank connections, offer selection, KYC, and contract signing).

> **Using the UI SDK?** The application lifecycle is managed automatically when the user interacts with the CTA. You do not need to implement any of the methods described below. See the [Prefilling Application Data](https://docs.wayflyer.com/embedded-finance/embedded-journey/prefilling-application-data) page if you want to pre-populate fields with data you already have.

## [Application lifecycle (Headless SDK)](#application-lifecycle-headless-sdk)

The following steps describe how to manage the application lifecycle when using the Headless SDK to build your own UI.

### [1\. Start the application](#_1-start-the-application)

When the user is ready to apply, call `startEmbeddedApplication()`. This creates an application and returns its status, including which details still need to be submitted.

```typescript
import type { EmbeddedApplicationStatusResponse } from '@wf-financing/headless-sdk';

const status: EmbeddedApplicationStatusResponse = await sdk.startEmbeddedApplication();

// status.application_id — the application ID (null if creation failed)
// status.required_details — list of required detail sections and their completion status
```

The `required_details` array contains entries for `user_details` and `company_details`, each with a status of `complete` or `incomplete`.

### [2\. Collect user details](#_2-collect-user-details)

Collect and submit the user's contact information (email, phone number).

```typescript
import type { UserDetailsRequest, UserDetailsResponse } from '@wf-financing/headless-sdk';

// Get current user details
const current: UserDetailsResponse = await sdk.getUserDetails();

// Update user details
const payload: UserDetailsRequest = {
  email: 'merchant@example.com',
  phone_number: '+353861234567',
};
const updated: UserDetailsResponse = await sdk.updateUserDetails(payload);
```

User details can only be updated a limited number of times and cannot be changed after the application is submitted.

### [3\. Collect company details](#_3-collect-company-details)

Collect business information including country, revenue, industry, and business type.

```typescript
import type { CompanyDetailsRequest, CompanyDetailsResponse } from '@wf-financing/headless-sdk';

// Get current company details
const current: CompanyDetailsResponse = await sdk.getCompanyDetails();

// Update company details
const updated: CompanyDetailsResponse = await sdk.updateCompanyDetails(payload);
```

Partners can also search for company registration details to pre-populate fields:

```typescript
const results = await sdk.searchCompanyRegistrationDetails({
  business_name: 'Acme',
  country: 'IE',
});
```

### [4\. Submit the application](#_4-submit-the-application)

Once all required details are complete, submit the application:

```typescript
await sdk.submitEmbeddedApplication();
```

After submission, details can no longer be edited. If required details are incomplete, the API will return an error with code `details_incomplete`.

### [5\. Handover to Wayflyer](#_5-handover-to-wayflyer)

After the embedded portion is complete, redirect the user to Wayflyer to finalise their application:

```typescript
import type { HandoverResponse } from '@wf-financing/headless-sdk';

const handover: HandoverResponse = await sdk.handover();
window.location.href = handover.url;
```

## [Continuing an application](#continuing-an-application)

The Embedded Journey handles continuation automatically. When a user returns to your platform with an in-progress application:

1.  The CTA will show the `continue_embedded_application` state.
2.  Opening the panel restores their progress — the journey resumes from where they left off.

Progress is saved automatically via `saveJourneyProgress()` and restored via `getJourneyProgress()`. Partners using the UI SDK do not need to manage this.

## [Error handling](#error-handling)

The `submitEmbeddedApplication()` method may return errors with the following codes:

| Error code                         | Description                                               |
| :--------------------------------- | :-------------------------------------------------------- |
| details_incomplete                 | Required user or company details have not been submitted. |
| no_open_application                | No open application exists for this company.              |
| open_hosted_application_exists     | A v4 hosted application is already in progress.           |
| duplicate_company                  | This company already exists on Wayflyer.                  |
| ineligible_application             | The company is not eligible for financing.                |
| registration_or_documents_required | Company registration or supporting documents are needed.  |