---
title: "Headless SDK"
description: "Learn how to use the Headless SDK to build a custom UI for the Embedded Journey"
url: "https://docs.wayflyer.com/embedded-journey-v5-overview/using-the-sdk/headless-sdk"
image: "https://docs.wayflyer.com/_og/d/c_Ocean.takumi,title_Headless+SDK,description_Learn+how+to+use+the+Headless+SDK+to+build+a+custom+UI+for+the+Embedded+Journey,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMyMzIzMmQifX19,p_Ii9lbWJlZGRlZC1qb3VybmV5LXY1LW92ZXJ2aWV3L3VzaW5nLXRoZS1zZGsvaGVhZGxlc3Mtc2RrIg,s_F8AUk8_NPl-qrf4V.png"
---

## Headless SDK

A typesafe wrapper around the Embedded Finance API for partners building their own UI.

# Headless SDK

The Headless SDK provides a typesafe wrapper around the Embedded Finance API. It handles API communication, caching, and cache invalidation, allowing partners to focus on building their own UI.

## [Installation](#installation)

Install the package from NPM:

```shell
npm install @wf-financing/headless-sdk
```

To minimize bundle size and reduce the impact on page load times, the SDK uses dynamic imports to load the required components on demand.

## [Instantiation](#instantiation)

Initialize the Wayflyer Headless SDK by passing the `companyToken` and an optional `options` object of type `HeadlessSdkOptions`.

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

// Production mode
const sdk = await WayflyerHeadlessSdk.loadSdk(companyToken);

// Sandbox mode
const options: HeadlessSdkOptions = { isSandbox: true };
const sdk = await WayflyerHeadlessSdk.loadSdk(companyToken, options);
```

The `companyToken` should be minted using the Company Token endpoint on the partner's backend. See the [Authentication](https://docs.wayflyer.com/embedded-journey-v5-overview/shared/authentication) guide for more details.

## [SDK methods](#sdk-methods)

### [CTA](#cta)

#### [`getCta()`](#getcta)

Returns the configuration for the CTA to show to the user.

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

const cta: BannerResponse | null = await sdk.getCta();
```

#### [`dismissCta()`](#dismisscta)

Dismiss the CTA for the current combination of company and user. Subsequent calls to `getCta()` will return `null` for a cooling-off period. Repeated dismissals result in an exponentially increasing backoff.

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

### [Embedded application](#embedded-application)

#### [`startEmbeddedApplication()`](#startembeddedapplication)

Start an embedded application for the company. Returns the application status including an optional application ID and a list of required detail statuses.

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

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

#### [`submitEmbeddedApplication()`](#submitembeddedapplication)

Submit the open embedded application for the authenticated company. Once submitted, some details can no longer be edited.

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

#### [`handover()`](#handover)

Returns a URL to redirect the user to the Wayflyer app after completing the embedded application.

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

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

### [User details](#user-details)

#### [`getUserDetails()`](#getuserdetails)

Get user details for the authenticated user.

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

const userDetails: UserDetailsResponse = await sdk.getUserDetails();
```

#### [`updateUserDetails(payload)`](#updateuserdetailspayload)

Update user details for the authenticated user. User details can only be updated a limited number of times and cannot be updated after an application is submitted.

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

const payload: UserDetailsRequest = {
  email: 'merchant@example.com',
  phone_number: '+353861234567',
};

const updated: UserDetailsResponse = await sdk.updateUserDetails(payload);
```

### [Company details](#company-details)

#### [`getCompanyDetails()`](#getcompanydetails)

Get company details for the authenticated company.

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

const companyDetails: CompanyDetailsResponse = await sdk.getCompanyDetails();
```

#### [`updateCompanyDetails(payload)`](#updatecompanydetailspayload)

Replace company details for the authenticated company. Company details can only be updated a limited number of times and cannot be updated after an application is submitted.

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

const updated: CompanyDetailsResponse = await sdk.updateCompanyDetails(payload);
```

#### [`searchCompanyRegistrationDetails(payload)`](#searchcompanyregistrationdetailspayload)

Search for company registration details by business name and country. Returns a list of matching company registration results.

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

const searchRequest: CompanyDetailsSearchRequest = {
  business_name: 'Acme',
  country: 'IE',
};

const results: CompanyDetailsSearchResponse = await sdk.searchCompanyRegistrationDetails(searchRequest);
```

### [Business classification](#business-classification)

#### [`searchIndustryClassifications(payload)`](#searchindustryclassificationspayload)

Search for industry classifications by query string. Returns a list of matching industries sorted by relevance.

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

const params: IndustrySearchParams = { query: 'software' };

const results: IndustrySearchResultResponse[] = await sdk.searchIndustryClassifications(params);
```

#### [`searchBusinessType()`](#searchbusinesstype)

Returns the list of business types available for company classification.

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

const businessTypes: BusinessType[] = await sdk.searchBusinessType();
```

#### [`searchEligibleBusinessModel(payload)`](#searcheligiblebusinessmodelpayload)

Validates the selected customer segments, sales channels, and product offerings for the given country and returns which combinations are eligible.

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

const response: DetermineBusinessModelsResponse = await sdk.searchEligibleBusinessModel(payload);
```

### [Document uploads](#document-uploads)

#### [`createDocumentUpload(payload)`](#createdocumentuploadpayload)

Request a presigned URL for uploading a document. The client must POST the file to the returned URL as multipart/form-data including the returned fields, then call `confirmDocumentUpload` with the returned `id`.

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

const request: CreateDocumentUploadRequest = {
  file_name: 'registration.pdf',
  file_type: 'application/pdf',
  file_size: 102400,
};

const upload: CreateDocumentUploadResponse = await sdk.createDocumentUpload(request);
```

#### [`confirmDocumentUpload(documentId)`](#confirmdocumentuploaddocumentid)

Mark a document as successfully uploaded. Must be called after the file has been uploaded to the URL returned by `createDocumentUpload`.

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

const confirmed: DocumentUploadResponse = await sdk.confirmDocumentUpload(documentId);
```

#### [`deleteDocumentUpload(documentId)`](#deletedocumentuploaddocumentid)

Remove a document. Documents attached to a submitted application cannot be deleted.

```typescript
await sdk.deleteDocumentUpload(documentId);
```

#### [`listDocumentUploads()`](#listdocumentuploads)

Returns confirmed and unconfirmed documents for the authenticated company.

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

const documents: DocumentUploadResponse[] = await sdk.listDocumentUploads();
```

### [Journey progress](#journey-progress)

#### [`getJourneyProgress()`](#getjourneyprogress)

Restore the saved journey step and draft for the authenticated company.

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

const progress: JourneyProgressResponse = await sdk.getJourneyProgress();
```

#### [`saveJourneyProgress(step, draftData, schemaVersion)`](#savejourneyprogressstep-draftdata-schemaversion)

Persist the current journey step and draft payload so the user can resume later.

```typescript
await sdk.saveJourneyProgress('contactDetails', draftData, 1);
```

#### [`deleteJourneyProgress()`](#deletejourneyprogress)

Delete the saved journey step and draft for the authenticated company.

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

## [Sandbox](#sandbox)

To simplify the testing process, the SDK can be initialized in sandbox mode. Pass the `isSandbox` option set to `true`. In sandbox mode, the partner can simulate responses for SDK methods with the help of the additional package `@wf-financing/sandbox-ui`.

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

const options: HeadlessSdkOptions = { isSandbox: true };
const sdk = await WayflyerHeadlessSdk.loadSdk(companyToken, options);
```