# Individual Customer Prefill

> Pre-populate the KYC questionnaire for an individual customer over the API, then run a hosted session to collect the remaining requirements.

## Overview

Through this solution, Noah enables you to provide KYC questionnaire data for an individual applicant. Pre-populate any existing KYC information you already have on the Customer and, after submitting the prefill data, run a Hosted Onboarding session to collect the remaining non-text-based KYC requirements (e.g., liveness checks, ID document uploads).

Use the [POST `onboarding/:CustomerID/prefill`](../../../api-reference/prefill-customer-details) endpoint to prefill individual customer data, with the `type` parameter set to `IndividualCustomerPrefill`.

Complete the onboarding process using the [POST `onboarding/:CustomerID`](../../../api-reference/create-onboarding-session) endpoint to collect:

- Missing compliance data through dynamic forms or hosted sessions
- Terms and Conditions acceptance for regulatory compliance
- Fiat currency selection configured during hosted onboarding

**Note:** Noah automatically identifies gaps in compliance data and collects only what's missing.

For more details on this process, see the [Hosted Onboarding](../onboarding/hosted-onboarding.md) recipe.

:::tip

`PrimaryResidence` must satisfy Noah's address validation rules — including required `State` and `PostCode`, US/CA ISO 3166-2 state codes, and printable ASCII. See [Address Validation](../../api-concepts/address-validation.md) for the full reference.

:::

:::warning Document and liveness capture

Individual prefill submits questionnaire and identity **metadata** via API. **Liveness checks** and document **images** cannot be embedded in the prefill request itself.

To upload identity or proof-of-address documents programmatically, use the separate [Get Document Upload URL](../../../api-reference/get-document-upload-url) endpoint after prefill. Otherwise, the customer can complete document capture in the hosted onboarding session.

If you already verify customers in Sumsub and want to reuse verified documents and liveness, use [Token Share Onboarding](./token-share-onboarding.md) instead.

:::

:::caution Enhanced Due Diligence (EDD)
Even after successful onboarding via prefill, customers may be subject to [Enhanced Due Diligence](../../api-concepts/compliance-freezes-refunds-reversals.md#what-triggers-enhanced-due-diligence) when they begin transacting. EDD can freeze deposits until documentation is provided. Make sure your integration handles this scenario — see [Compliance Freezes, Refunds & Reversals](../../api-concepts/compliance-freezes-refunds-reversals.md) for details.
:::

## Recipe

Implement a scenario as described above by following the steps below.

<details>

<summary>1. Provide Individual Customer Details</summary>

Provide the applicable individual customer details via the [POST `onboarding/:CustomerID/prefill`](../../../api-reference/prefill-customer-details) endpoint. In this step, you query the [POST `onboarding/:CustomerID/prefill`](../../../api-reference/prefill-customer-details) endpoint, selecting the `IndividualCustomerPrefill` type:

```typescript
curl -L 'https://api.sandbox.noah.com/v1/onboarding/:CustomerID/prefill' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
-d '{
  "Type": "IndividualCustomerPrefill",
  "FullName": {
    "FirstName": "John",
    "LastName": "Doe"
  },
  "DateOfBirth": "1990-05-15",
  "Email": "john.doe@example.com",
  "PhoneNumber": "+12125551234"
}'
```

As can be seen above, include your API Key in the header, along with all the individual customer details that are relevant in your context.

While the above is a typical request in this context, below is a comprehensive request, with all the available parameters and comments included.

<!-- prettier-ignore -->
```json
{
  "Type": "IndividualCustomerPrefill",

  // Full name of the individual
  "FullName": {
    "FirstName": "John", // First/given name (1-50 characters)
    "MiddleName": "Michael", // Middle name (1-50 characters)
    "LastName": "Doe" // Last/family name (1-50 characters)
  },

  // Date of birth (YYYY-MM-DD format)
  "DateOfBirth": "1990-05-15",

  // Identity documents
  "Identities": [
    {
      "IssuingCountry": "US", // Issuing country of the identity, ISO 3166-1 alpha-2 country code
      "IDNumber": "123456789", // ID number (1-36 characters)
      // IDType options: DrivingLicense, NationalIDCard,
      // Passport, AddressProof, ResidencePermit, TaxID
      "IDType": "Passport",
      "IssuedDate": "2020-01-01", // Issue date (YYYY-MM-DD format)
      "ExpiryDate": "2030-01-01" // Expiry date (YYYY-MM-DD format)
    }
  ],

  // Primary residence address
  "PrimaryResidence": {
    "Street": "123 Main Street", // Street: the primary name of an address street (2-200 characters)
    "Street2": "Apt 4B", // Street2: the secondary name of an address street
    "City": "New York", // City: name of an address city or town (1-100 characters)
    "PostCode": "10001", // PostCode: the address postcode (1-20 characters)
    "State": "NY", // State: the address state/province/county. For USA and Canada, state code in ISO 3166-2 code (e.g. CA) is required (1-100 characters)
    "Country": "US" // ISO 3166-1 alpha-2 country code
  },

  // Country of citizenship (ISO 3166-1 alpha-2 country code)
  "Citizenship": "US",

  // Tax residence country (ISO 3166-1 alpha-2 country code)
  "TaxResidenceCountry": "US",

  // Customer's email address
  "Email": "john.doe@example.com",

  // Phone number (format: +[0-9]{6,15})
  "PhoneNumber": "+12125551234",

  // What's your main source of income?
  // Options: Salary, Pension, Investment, Property, FriendsAndFamily, Benefits
  "SourceOfIncome": "Salary",

  // What's your employment status?
  // Options: Employed, Unemployed, Retired, Student, SelfEmployed
  "EmploymentStatus": "Employed",

  // What industry do you work in?
  // Options: BankingAndFinancialServices, InvestmentAndSecurities, Insurance, RealEstate,
  //          LegalServices, AccountingAndAuditing, GamingAndGambling, MiningAndEnergy,
  //          RetailAndECommerce, HealthcareAndPharmaceuticals, GovernmentAndPublicSector,
  //          NonProfitAndCharity, TechnologyAndSoftwareDevelopment, TransportationAndLogistics,
  //          HospitalityAndTourism
  "WorkIndustry": "TechnologyAndSoftwareDevelopment",

  // Financial information in USD
  "FinancialsUsd": {
    // What's your expected annual deposit?
    // Options: LessThan5k, 5kTo50k, 50kTo150k, MoreThan150k
    "AnnualDeposit": "50kTo150k"
  },

  // What's your expected frequency of transactions?
  // Options: OncePerYear, OnceEveryFewMonths, AFewTimesPerMonth, OncePerWeek, MoreThanOncePerWeek
  "TransactionFrequency": "AFewTimesPerMonth"
}
```

</details>

<details>

<summary>2. Initiate a Hosted Onboarding Session</summary>

Submit a call to the [POST `onboarding/:CustomerID`](../../../api-reference/create-onboarding-session) endpoint, to collect the prerequisite Terms and Conditions acceptance from your customer (and any missing data as per the prefill above):

```typescript
curl -L 'https://api.sandbox.noah.com/v1/onboarding/:CustomerID' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
-d '{
  "Metadata": {},
  "ReturnURL": "https://example.com",
  "FiatOptions": [
    {
      "FiatCurrencyCode": "USD"
    }
  ]
}'
```

As can be seen above, in your request, include your API Key in the header along with a `CustomerID`, the URL to which the user is redirected at the end of the Hosted Onboarding session, and the list of fiat options to be supported by the customer.

:::note

Noah expects a full `ReturnURL` value, including the `https://`.

:::

View the [POST `onboarding/:CustomerID`](../../../api-reference/create-onboarding-session) endpoint for detailed instructions on initiating a session.

The response will consist of a `HostedURL`, where the Hosted Onboarding session is ready for the
customer to enter their details:

```typescript
{"HostedURL":"https://checkout.sandbox.noah.com/kyc?session=xyz"}
```

</details>

<details>

<summary>3. Direct the Customer to Hosted Onboarding</summary>

Redirect your customer to the `HostedURL` to enter their details in the Hosted Onboarding session.

</details>

<details>

<summary>4. Customer Status Updates via Webhooks</summary>

Set up to receive notifications through webhooks about the status of the Hosted Onboarding session,
which can be `Pending`, `Approved`, or `Declined`.

For more details, see [Customer Webhooks](../../api-concepts/webhooks/customer.md).

</details>

<details>

<summary>5. Close the Hosted Onboarding Session</summary>

Noah emits a `postMessage` once the onboarding process is complete. You can listen to this event in your application, as follows:

```typescript
window.addEventListener('message', (event) => {
  if (event.data?.type === 'kycCompleted') {
    closeHostedSession(); // <-- Replace this with platform-specific close method
  }
});
```

:::tip

- The message sent is: `{ type: 'kycCompleted' }`
- It is sent once a valid KYC review status is detected.

:::

</details>