> 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-embedded-wallet-service/user-management/get-kyc-status.md).

# Get KYC Status

Retrieves detailed KYC and verification information for an end user.

### Endpoint

```http
GET /whitelabel/users/getKycStatus
```

### Request Headers

```http
x-tlp-apikey: <api-key>
x-tlp-signature: <hmac-signature>
```

### Query Parameters

Provide at least one of the following user identifiers: `endUserEmail`, `endUserId`, or `externalUserId`.

| Field            | Type   |    Required | Description                         |
| ---------------- | ------ | ----------: | ----------------------------------- |
| `endUserEmail`   | String | Conditional | End user’s registered email address |
| `endUserId`      | Number | Conditional | Tylt's end-user ID                  |
| `externalUserId` | String | Conditional | Merchant’s own user identifier      |

### Example Request

```http
GET /whitelabel/users/getKycStatus?externalUserId=user-10021
```

The signature must be calculated over:

```json
{
  "endUserId": 20001, // Optional: Provide one user identifier only
  "endUserEmail": "joe@example.com", // Optional: Alternative to endUserId and externalUserId
  "externalUserId": "user-10021", // Optional: Alternative to endUserId and endUserEmail
}
```

### Code Snippet

{% tabs %}
{% tab title="JavaScript (Axios)" %}

```javascript
import crypto from 'crypto';
import axios from 'axios';

const apiKey = 'your-api-key';
const apiSecret = 'your-api-secret';

const queryParams = {
  endUserId: 20001, // Optional: Provide one user identifier only
  endUserEmail: "joe@example.com", // Optional: Alternative to endUserId and externalUserId
  externalUserId: "user-10021", // Optional: Alternative to endUserId and endUserEmail
};

const rawPayload = JSON.stringify(queryParams);
const signature = crypto.createHmac('sha256', apiSecret).update(rawPayload).digest('hex');

const headers = {
    'x-tlp-apikey': apiKey,
    'x-tlp-signature': signature
};

const queryString = new URLSearchParams(queryParams).toString();
axios.get(`https://api.tylt.money/whitelabel/users/getKycStatus?${queryString}`, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error.response ? error.response.data : error.message));
```

{% endtab %}
{% endtabs %}

### Successful Response

```json
{
  "msg": "",
  "data": {
    "endUserId": 1012,
    "kycV2": {
      "overallKycStatus": "approved",
      "poiStatus": "approved",
      "poaStatus": "approved",
      "kycCompletedAt": "2026-07-20T10:30:00.000Z"
    },
    "eurKyc": {
      "kycId": 7788,
      "kycStatus": "APPROVED",
      "diditSessionId": "wl-owner2-user1012",
      "documentTypeFromDidit": "PASSPORT"
    },
    "walletOpsAllowed": true
  }
}
```

### Response Fields

#### Main Response

| Field              | Description                                       |
| ------------------ | ------------------------------------------------- |
| `endUserId`        | Tylt end-user ID                                  |
| `kycV2`            | Tylt KYC status information                       |
| `eurKyc`           | External verification-provider information        |
| `walletOpsAllowed` | Indicates whether wallet operations are permitted |

#### `kycV2`

| Field              | Description                          |
| ------------------ | ------------------------------------ |
| `overallKycStatus` | Overall KYC result                   |
| `poiStatus`        | Proof-of-identity status             |
| `poaStatus`        | Proof-of-address status              |
| `kycCompletedAt`   | Date and time when KYC was completed |

#### `eurKyc`

| Field                   | Description                                  |
| ----------------------- | -------------------------------------------- |
| `kycId`                 | Internal KYC record ID                       |
| `kycStatus`             | Verification-provider KYC status             |
| `diditSessionId`        | Verification session identifier              |
| `documentTypeFromDidit` | Document type identified during verification |

The `kycV2` and `eurKyc` objects may be `null` where the end user has not yet submitted KYC information.

### Example: No KYC Submitted

```json
{
  "msg": "",
  "data": {
    "endUserId": 1012,
    "kycV2": null,
    "eurKyc": null,
    "walletOpsAllowed": false
  }
}
```

### Possible Errors

| HTTP Status | Message                                                         | Description                                        |
| ----------- | --------------------------------------------------------------- | -------------------------------------------------- |
| `400`       | `One of endUserEmail, endUserId or externalUserId is required.` | No user identifier was supplied                    |
| `401`       | `Api Key authentication failed!`                                | Authentication failed                              |
| `403`       | `API key or owner is inactive.`                                 | API access or merchant account is inactive         |
| `403`       | `IP not whitelisted.`                                           | Request originated from an unauthorized IP address |
| `403`       | `End user is suspended.`                                        | The identified user is suspended                   |
| `404`       | `End user not found for this owner.`                            | No matching user exists under the merchant         |

***