> For the complete documentation index, see [llms.txt](https://docs.tylt.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tylt.money/tylt-crossramp-fiat-crypto-solutions/user-kyc-verification-apis/hosted-kyc-widget.md).

# Hosted KYC Widget

Creates a new KYC instance for an individual user and returns a hosted KYC link that can be shared with the user to complete verification.

This endpoint is intended for server-to-server use only and must be called from the merchant's backend.

### Endpoint

```http
POST https://api.tylt.money/kycIndividualUserMerchant/createKYCLinkIndividualUser
```

### Authentication

The request must include the merchant API key and an HMAC-SHA256 signature.

| Header            | Description                                                             |
| ----------------- | ----------------------------------------------------------------------- |
| `x-tlp-apikey`    | Merchant API key                                                        |
| `x-tlp-signature` | HMAC-SHA256 signature of the request body using the merchant API secret |
| `Content-Type`    | `application/json`                                                      |

The merchant is identified from the API key. `merchantId` and `userId` must not be included in the request body.

***

### Request Parameters

| Field       | Type   | Required | Description                                                                           |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `userEmail` | string | Yes      | Valid email address of the individual user for whom the KYC instance is being created |

#### Example Request Body

```json
{
  "userEmail": "user@example.com"
}
```

***

### Example Request

The request signature must be generated from the exact JSON body being sent.

```javascript
import crypto from "crypto";
import axios from "axios";

const apiKey = process.env.TYLT_API_KEY;
const apiSecret = process.env.TYLT_API_SECRET;

const body = {
  userEmail: "user@example.com",
};

const bodyString = JSON.stringify(body);

const signature = crypto
  .createHmac("sha256", apiSecret)
  .update(bodyString)
  .digest("hex");

const response = await axios.post(
  "https://<host>/kycIndividualUserMerchant/createKYCLinkIndividualUser",
  bodyString,
  {
    headers: {
      "Content-Type": "application/json",
      "x-tlp-apikey": apiKey,
      "x-tlp-signature": signature,
    },
  }
);

console.log(response.data);
```

#### Signature Generation

The signature is calculated as:

```
HMAC-SHA256(apiSecret, JSON.stringify(body))
```

The resulting hexadecimal digest must be passed as the `x-tlp-signature` header.

The JSON string used to generate the signature must exactly match the request body sent to the API.

***

### Validation Requirements

The merchant should ensure that:

* `userEmail` contains a valid email address.
* The request is made from the merchant's backend.
* `x-tlp-apikey` and `x-tlp-signature` are included in the request headers.
* The signature is generated using the exact JSON request body.

The merchant identity is automatically resolved from the API key after the signature has been validated.

***

### Response

#### Success Response

**HTTP 201 — Created**

```json
{
  "msg": "KYC instance created successfully.",
  "data": {
    "kycInstanceId": "550e8400-e29b-41d4-a716-446655440000",
    "userEmail": "user@example.com",
    "merchantId": 123,
    "kycLink": "https://app.tylt.money/kyc?kycInstanceId=550e8400-e29b-41d4-a716-446655440000"
  }
}
```

#### Response Parameters

| Field           | Type   | Description                                                                 |
| --------------- | ------ | --------------------------------------------------------------------------- |
| `kycInstanceId` | string | Unique identifier of the KYC instance                                       |
| `userEmail`     | string | Email address of the individual user                                        |
| `merchantId`    | number | Merchant associated with the authenticated API key                          |
| `kycLink`       | string | Hosted KYC URL that should be shared with or opened for the individual user |

The merchant should store the `kycInstanceId` against the user. It can be used to identify the KYC instance for subsequent status checks and KYC operations.

The returned `kycLink` should be used to redirect the user to the hosted KYC verification flow.

***

### Error Responses

#### Invalid User Email

**HTTP 400**

```json
{
  "msg": "A valid userEmail is required.",
  "data": {}
}
```

Returned when `userEmail` is missing, empty, or invalid.

#### Invalid Signature

**HTTP 400**

```json
{
  "msg": "Invalid signature.",
  "data": {}
}
```

Returned when the supplied HMAC signature does not match the request body.

#### Missing Authentication Headers

**HTTP 401**

```json
{
  "msg": "API key and signature headers are required.",
  "data": {}
}
```

Returned when `x-tlp-apikey` or `x-tlp-signature` is missing.

#### Invalid API Key

**HTTP 401**

```json
{
  "msg": "Invalid API key.",
  "data": {}
}
```

Returned when the supplied merchant API key is not recognized.

#### Merchant Identity Missing

**HTTP 403**

```json
{
  "msg": "Merchant identity is missing.",
  "data": {}
}
```

Returned when the API key is not associated with a valid merchant.

#### Server Error

**HTTP 500**

```json
{
  "msg": "Failed to create KYC instance.",
  "data": {}
}
```

Returned when the KYC instance cannot be created because of an internal server or database error.

***

### cURL Example

Generate the `x-tlp-signature` from the exact request body using the merchant API secret.

```bash
curl --location 'https://<host>/kycIndividualUserMerchant/createKYCLinkIndividualUser' \
  --header 'Content-Type: application/json' \
  --header 'x-tlp-apikey: <your_api_key>' \
  --header 'x-tlp-signature: <hmac_sha256_hex>' \
  --data '{"userEmail":"user@example.com"}'
```

***

### Next Step

After receiving the `kycLink`, redirect or share the URL with the individual user.

The hosted KYC flow will collect the required user information and initiate the applicable verification modules, including:

* Basic identity information
* Proof of Identity (POI)
* Proof of Address (POA)
* AML screening
* Liveness verification