> For the complete documentation index, see [llms.txt](https://docs.zk.me/hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zk.me/hub/start/onboarding/integration/api/verify-zkkyc.md).

# Verify zkKYC Status

{% hint style="info" %}
Before making any API requests, please refer to the [zkMe API](/hub/start/onboarding/integration/api.md#getting-started) section on the [zkMe API](/hub/start/onboarding/integration/api.md) page to obtain the necessary API access parameters.
{% endhint %}

## Get Users List <a href="#get-users-list" id="get-users-list"></a>

Returns a list of users who initiated the verification flow under a dashboard account.

{% tabs %}
{% tab title="Endpoint" %}

```ruby
POST https://agw.zk.me/zkseradmin/openapi/kyc/getUsersList
```

{% endtab %}

{% tab title="Request" %}

#### Request Body <a href="#parameters" id="parameters"></a>

```json
{
  "mchNo": "YourAppID" ,
  "apiKey": "YourApiKey",
  "programNo": "YourProgramNo",
  "page": 1,
}
```

#### Fields Explanation <a href="#parameters" id="parameters"></a>

<table><thead><tr><th width="206">Name</th><th width="155">Type</th><th>Description</th></tr></thead><tbody><tr><td>mchNo</td><td>string</td><td>Same as AppID in the <a href="https://dashboard.zk.me/integration">Dashboard</a>.</td></tr><tr><td>apiKey</td><td>string</td><td>Your API Key.</td></tr><tr><td>programNo</td><td>string</td><td>Same as the programNo you pass for the SDK integration. </td></tr><tr><td>page</td><td>integer</td><td>Returns users in blocks of 50 (page 1 = 1–50, page 2 = 51–100, etc.). If fewer users exist, all are returned.</td></tr></tbody></table>
{% endtab %}

{% tab title="Response" %}

#### Sample Response <a href="#sample-response" id="sample-response"></a>

```json
{
  "code": ...,
  "data": {
    "total": ...,
    "totalPage": ...,
    "users": [
      {
        "clientUserIdentifier": [
          {
            "blockchainId": ...,
            "network": "...",
            "tokenId": "...",
            "userId": ...,
            "walletAddress": "..."
          }
        ],
        "completedTimeUnix": "...",
        "ssiWallet": "...",
        "status": "...",
        "zkmeAccount": "...",
        "zkmeId": "..."
      },
    ]
  },
  "msg": "...",
  "timestamp": ...
}
```

#### Fields Explanation <a href="#parameters" id="parameters"></a>

| Name      | Type   | Description                                             |
| --------- | ------ | ------------------------------------------------------- |
| code      | number | Business status code, e.g. `80000000` indicates success |
| msg       | string | Message describing the result                           |
| timestamp | number | Response timestamp in Unix milliseconds                 |
| data      | object | Main data object (see **`data` Object** below)          |

***

**`data` Object**

| Name      | Type           | Description                                   |
| --------- | -------------- | --------------------------------------------- |
| total     | number         | Total number of users matched                 |
| totalPage | number         | Total number of pages                         |
| users     | array\<object> | List of user objects (see **`users` Object**) |

***

**`users` Object**

<table><thead><tr><th width="182.548828125">Name</th><th width="128.3125">Type</th><th>Description</th></tr></thead><tbody><tr><td>clientUserIdentifier</td><td>array&#x3C;object></td><td>Identifiers linked to this user (see <strong><code>clientUserIdentifier</code> Object</strong>)</td></tr><tr><td>completedTimeUnix</td><td>string</td><td>Completion time (Unix milliseconds, as string)</td></tr><tr><td>ssiWallet</td><td>string</td><td>zkMe SSI wallet address bound to the user.</td></tr><tr><td>status</td><td>string</td><td><p>Current KYC/verification status. Possible values include:</p><ul><li>Verification Started</li><li>OCR Passed</li><li>Liveness Checked</li><li>ZKP Generated</li><li>SBT Minted</li><li><p>OnChain Minted</p><ul><li>Note: Only applicable to <a href="/pages/OUIXBnh5tvUU4oUY9vs5#on-chain-mint-default">On-chain Mint</a> </li></ul></li><li>KYC Passed</li><li>Verification Failed</li></ul></td></tr><tr><td>zkmeAccount</td><td>string</td><td>The email address used to log in to zkMe.</td></tr><tr><td>zkmeId</td><td>string</td><td>Unique zkMe user ID</td></tr></tbody></table>

{% hint style="info" %}
**Note:** <kbd>`clientUserIdentifier`</kbd> will be empty if the user’s `status` has not yet reached `KYC_PASSED`.
{% endhint %}

***

**`clientUserIdentifier` Object**

<table><thead><tr><th width="129.77734375">Name</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>blockchainId</td><td>number</td><td>Chain ID</td></tr><tr><td>network</td><td>string</td><td>Chain name </td></tr><tr><td>tokenId</td><td>string</td><td>The ID of the Soulbound Token (SBT) minted for the user on the chain.</td></tr><tr><td>walletAddress</td><td>string</td><td>User’s wallet address from the client system.</td></tr><tr><td>userId</td><td>string</td><td>User’s email address, or another non-wallet unique identifier from the client system.</td></tr></tbody></table>

{% hint style="info" %}
**Note:**&#x20;

The returned fields are returned is determined by the configured [**decentralization level**](/hub/start/onboarding/zkkyc-levels.md)**:**&#x20;

* For [On-chain Mint](/hub/start/onboarding/zkkyc-levels.md#on-chain-mint-default) integrations, the fields `blockchainId`, `network`, `tokenId`, and `walletAddress` are returned. `userId` is not returned.
* For [Cross-chain](/hub/start/onboarding/zkkyc-levels.md#cross-chain) integrations, only `userId`  is returned.
  {% endhint %}

***

{% endtab %}
{% endtabs %}

## Get Users KYC Result Overview  <a href="#get-get-users-kyc-result-overview" id="get-get-users-kyc-result-overview"></a>

Returns the verification status of the user for the following credentials: [Proof-of-Citizenship (PoC)](/hub/what/zkkyc/zkpoc.md), [Proof-of-Location (PoL)](/hub/what/zkkyc/zkpol.md), and [AML Check (zkAML)](/hub/what/zkkyc/amlme.md).&#x20;

{% tabs %}
{% tab title="Endpoint" %}

```ruby
POST https://agw.zk.me/zkseradmin/openapi/queryKycInfoByAddress
```

{% endtab %}

{% tab title="Request" %}

#### Request Body <a href="#parameters" id="parameters"></a>

```json
{
  "mchNo": "YourAppID" ,
  "apiKey": "YourApiKey",
  "programNo": "YourProgramNo",
  "account": "walletAddress", // or email, or other unique identifiers
  "chainId": "YourChainID"
}
```

#### Fields Explanation <a href="#parameters" id="parameters"></a>

<table><thead><tr><th width="206">Name</th><th width="155">Type</th><th>Description</th></tr></thead><tbody><tr><td>mchNo</td><td>string</td><td>Same as AppID in the <a href="https://dashboard.zk.me/integration">Dashboard</a>.</td></tr><tr><td>apiKey</td><td>string</td><td>Your API Key.</td></tr><tr><td>programNo</td><td>string</td><td>Same as the programNo you pass for the SDK integration. </td></tr><tr><td>account</td><td>string</td><td>User's wallet address (recommended), email address, or other unique identifier</td></tr><tr><td>chainId</td><td>string</td><td>Same as the param chainId you pass for the SDK integration. </td></tr></tbody></table>

#### Supported Chain List

{% tabs %}
{% tab title="Mainnet" %}

| Chain Name      | zkMe Chain ID |
| --------------- | ------------- |
| Aptos           | aptos-1       |
| Arbitrum        | 42161         |
| Base            | 8453          |
| BNB Smart Chain | 56            |
| BounceBit       | 6001          |
| Ethereum        | 1             |
| Kaia            | 8217          |
| Manta           | 169           |
| Neutron         | neutron-1     |
| Polygon         | 137           |
| Ronin           | 2020          |
| Solana          | solana        |
| TON             | ton           |
| {% endtab %}    |               |

{% tab title="Testnet" %}

| Chain Name                | zkMe Chain ID |
| ------------------------- | ------------- |
| Aptos Testnet             | aptos-2       |
| Plume Testnet             | 98864         |
| Scroll Sepolia Testnet    | 534351        |
| Sei Testnet               | atlantic-2    |
| ZetaChain Athens3 Testnet | 7001          |
| {% endtab %}              |               |
| {% endtabs %}             |               |
| {% endtab %}              |               |

{% tab title="Response" %}

#### Sample Response <a href="#sample-response" id="sample-response"></a>

```json
{
  "zkme_id":"...",
  "kycStatus":"...",
  "kycCompleteTimeUnix":"...", 
  "ssiAddress":"...",
  "verifierValues":{
    "sanction":...,
    "age":...,
    "citizenship":...,
    "location":...,
    "unique":...,
  },
}
```

#### Fields Explanation <a href="#fields" id="fields"></a>

<table><thead><tr><th width="218">Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>zkme_id</td><td>string</td><td>Return the zkMe id corresponding to the zkMe account linked to the provided address.</td></tr><tr><td>kycStatus</td><td>string</td><td><p>Return users' KYC status, including 8-9 stages: </p><ul><li>Not Started</li><li>Verification Started</li><li>OCR Passed</li><li>Liveness Checked</li><li>ZKP Generated</li><li>SBT Minted</li><li><p>OnChain Minted</p><ul><li>Note: Only applicable to <a href="/pages/OUIXBnh5tvUU4oUY9vs5#on-chain-mint-default">On-chain Mint</a> </li></ul></li><li>KYC Passed</li><li>Verification Failed</li></ul></td></tr><tr><td>kycCompleteTimeUnix</td><td>string</td><td>Unix timestamp of the mint time of SBT minting in SSI wallet.</td></tr><tr><td>ssiAddress</td><td>string</td><td>User's SSI wallet address.</td></tr><tr><td>verifierValues</td><td>object</td><td>List of verifierValues objects (see <strong><code>verifierValues</code> Object</strong>)</td></tr></tbody></table>

***

**`verifierValues` Object**

<table><thead><tr><th width="218">Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>sanction</td><td>bool</td><td><p>Return the user's AML Screening verification result with the following output:</p><ul><li>If the user passes, return <code>true</code>.</li><li>If the user fails, return <code>false</code>.</li><li>If the AML Screening verification is not configured for the program, return <code>null</code>.</li></ul></td></tr><tr><td>age</td><td>bool</td><td><p>Return the user's age verification result with the following output:</p><ul><li>If the user passes, return <code>true</code>.</li><li>If the user fails, return <code>false</code>.</li><li>If the Proof of Citizenship is not configured for this program, return <code>null</code>.</li></ul></td></tr><tr><td>citizenship</td><td>bool</td><td><p>Return the user's citizenship verification result with the following output:</p><ul><li>If the user passes, return <code>true</code>.</li><li>If the user fails, return <code>false</code>.</li><li>If the Proof of Citizenship is not configured for the program, return <code>null</code>.</li></ul></td></tr><tr><td>location</td><td>bool</td><td><p>Return the user's location verification result with the following output:</p><ul><li>If the user passes, return <code>true</code>.</li><li>If the user fails, return <code>false</code>.</li><li>If the Proof of Location is not configured for the program, return <code>null</code>.</li></ul></td></tr><tr><td>unique</td><td>bool</td><td><p>Return the user's ID-based uniqueness verification result with the following output:</p><ul><li>If the user passes, return <code>true</code>.</li><li>If the user fails, return <code>false</code>.</li><li>If the Uniqueness Check is not configured for the program, return <code>null</code>.</li></ul></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Get Users Address Proof Result Overview

Returns the verification status of the user for the following credentials: [Proof-of-Address (PoA)](/hub/what/zkkyc/zkpoa.md).&#x20;

{% tabs %}
{% tab title="Endpoint" %}

```ruby
POST https://agw.zk.me/zkseradmin/openapi/queryPoAInfoByAddress 
```

{% endtab %}

{% tab title="Request" %}

#### Request Body <a href="#parameters" id="parameters"></a>

```json
{
  "mchNo": "YourAppID" ,
  "apiKey": "YourApiKey",
  "programNo": "YourProgramNo",
  "account": "walletAddress", // or email, or other unique identifiers
}
```

#### Fields Explanation <a href="#parameters" id="parameters"></a>

<table><thead><tr><th width="206">Name</th><th width="155">Type</th><th>Description</th></tr></thead><tbody><tr><td>mchNo</td><td>string</td><td>Same as AppID in the <a href="https://dashboard.zk.me/integration">Dashboard</a>.</td></tr><tr><td>apiKey</td><td>string</td><td>Your API Key.</td></tr><tr><td>programNo</td><td>string</td><td>Same as the programNo you pass for the SDK integration. </td></tr><tr><td>account</td><td>string</td><td>User's wallet address (recommended), email address, or other unique identifier</td></tr></tbody></table>
{% endtab %}

{% tab title="Response" %}

#### Sample Response <a href="#sample-response" id="sample-response"></a>

```json
{
    "code": ...,
    "data": [
        {
            "completedTimeUnix": "...",
            "ssiAddress": "...",
            "status": "...",
            "verifierValues": {
                "countryRegion": ...
            },
            "zkmeId": "..."
        }
    ],
    "msg": "...",
    "timestamp": ...
}
```

#### Fields Explanation <a href="#fields" id="fields"></a>

| Name      | Type   | Description                                             |
| --------- | ------ | ------------------------------------------------------- |
| code      | number | Business status code, e.g. `80000000` indicates success |
| msg       | string | Message describing the result                           |
| timestamp | number | Response timestamp in Unix milliseconds                 |
| data      | object | Main data object (see **`data` Object** below)          |

***

**`data` Object**

<table><thead><tr><th width="218">Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>completedTimeUnix</td><td>string</td><td>Unix timestamp of the mint time of SBT minting in SSI wallet.</td></tr><tr><td>ssiAddress</td><td>string</td><td>User's SSI wallet address.</td></tr><tr><td>status</td><td>string</td><td><p>Return users' KYC status, including 7 stages: </p><ul><li>Not Started</li><li>Verification Started</li><li>OCR Passed</li><li>ZKP Generated</li><li>SBT Minted</li><li>Verification Passed</li><li>Verification Failed</li></ul></td></tr><tr><td>zkme_id</td><td>string</td><td>Return the zkMe id corresponding to the zkMe account linked to the provided address.</td></tr><tr><td>verifierValues</td><td>object</td><td>List of verifierValues objects (see <strong><code>verifierValues</code> Object</strong>)</td></tr></tbody></table>

***

**`verifierValues` Object**

<table><thead><tr><th width="218">Name</th><th width="96">Type</th><th>Description</th></tr></thead><tbody><tr><td>countryRegion</td><td>bool</td><td><p>Return the user's Address verification result with the following output:</p><ul><li>If the user passes, return <code>true</code>.</li><li>If the user fails, return <code>false</code>.</li><li>If the AML Screening verification is not configured for the program, return <code>null</code>.</li></ul></td></tr></tbody></table>
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zk.me/hub/start/onboarding/integration/api/verify-zkkyc.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.