> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portalhq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ramps.noah.initiateKyc

> Start hosted Noah KYC onboarding and return a hosted URL.

## Function Signature

```dart theme={null}
Future<NoahInitiateKycResponse> initiateKyc(NoahInitiateKycRequest request)
```

## Description

Starts a Noah KYC session for the current customer and returns a hosted onboarding URL. The SDK does not open the URL: open it in the system browser after validating its scheme and hostname.

While the customer's KYC is pending, each call starts a new onboarding session and returns a new `hostedUrl`. Once KYC is approved or declined, it returns the stored `hostedUrl` without starting a new session.

The KYC outcome is delivered asynchronously through Noah `Customer` webhooks, not through this response.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `request.returnUrl` | `String` | Yes | HTTPS URL where Noah returns the user after onboarding. Custom app schemes are not supported. |
| `request.fiatOptions` | `List<NoahFiatOption?>?` | No | Fiat currencies to present during onboarding. |
| `request.customerType` | `String?` | No | Onboarding flow variant — `NoahCustomerType.individual.value` or `NoahCustomerType.business.value`. |
| `request.metadataJson` | `String?` | No | JSON-encoded object of opaque metadata, forwarded per API rules. |
| `request.formJson` | `String?` | No | JSON-encoded prefill payload for hosted forms. |

## Returns

**`NoahInitiateKycResponse`** - An envelope containing:

| Property | Type | Description |
| - | - | - |
| `data` | `NoahInitiateKycData` | The response payload. |
| `metadataJson` | `String?` | JSON-encoded response metadata. Read it decoded through the `metadata` getter. |

`NoahInitiateKycData`:

| Property | Type | Description |
| - | - | - |
| `hostedUrl` | `String` | Hosted Noah onboarding URL to open in the system browser. |

## Example

This example opens the URL with the [`url_launcher`](https://pub.dev/packages/url_launcher) package.

```dart theme={null}
import 'package:portal_flutter/portal_flutter.dart';
import 'package:url_launcher/url_launcher.dart';

final portal = Portal();

const allowedHosts = {
  'checkout.noah.com',
  'checkout.sandbox.noah.com',
  'staging-checkout.noah.com',
};

try {
  final response = await portal.ramps.noah.initiateKyc(
    NoahInitiateKycRequest(
      returnUrl: 'https://yourapp.example/noah/return',
      fiatOptions: [NoahFiatOption(fiatCurrencyCode: 'USD')],
      customerType: NoahCustomerType.individual.value,
    ),
  );

  final uri = Uri.tryParse(response.data.hostedUrl);
  if (uri != null && uri.scheme == 'https' && allowedHosts.contains(uri.host)) {
    await launchUrl(uri, mode: LaunchMode.externalApplication);
  } else {
    // Handle this however your app prefers — surface it, log it, or fail the flow.
    print('Noah returned an unexpected KYC URL: ${response.data.hostedUrl}');
  }
} on PortalException catch (e) {
  print('initiateKyc failed: [${e.code}] ${e.message}');
}
```

## Errors

| Code | Description |
| - | - |
| `NOT_INITIALIZED` | Portal was not initialized |
| `NOAH_INITIATE_KYC_ERROR` | Failed to initiate Noah KYC — for example an invalid `returnUrl`, or Noah is not enabled for your environment |

## Related

* [Noah virtual accounts and payouts guide](../guide/noah)
* [Noah KYC workflow](/integrations/On-Off-Ramp/noah-kyc)
* [Noah webhooks](/integrations/On-Off-Ramp/noah-webhooks)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.