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

# Get KYC status

> Return verification status, session metadata, IP summaries, and blocklist signal for an email.

<ParamField header="x-api-key" type="string" required placeholder="your-api-key">
  Your StarkFi API key when required by your environment.
</ParamField>

<ParamField query="email" type="string">
  Email associated with the KYC session. Provide **email** or **wallet**.
</ParamField>

<ParamField query="wallet" type="string">
  Wallet associated with the KYC session. Provide **wallet** or **email**.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.starkfi.io/kyc/status?email=user@example.com' \
    --header 'x-api-key: <api_key>'
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ email: "user@example.com" });
  const response = await fetch(
    `https://api.starkfi.io/kyc/status?${params}`,
    { headers: { "x-api-key": "<api_key>" } }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.starkfi.io/kyc/status",
      params={"email": "user@example.com"},
      headers={"x-api-key": "<api_key>"},
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "statusCode": 200,
    "success": true,
    "status": "kyc_status_retrieved",
    "message": "KYC status retrieved",
    "data": {
      "status": "pending",
      "approved": false,
      "session_id": "string",
      "session_status": "string",
      "session_url": "https://...",
      "ip_info": [],
      "is_blocklisted": false
    }
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "statusCode": 400,
    "success": false,
    "status": "missing_params",
    "message": "email or wallet is required"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "statusCode": 404,
    "success": false,
    "status": "kyc_not_found",
    "message": "User KYC not found"
  }
  ```

  The `status` value matches the failure reason returned by the server (for example `kyc_not_found` when no session exists for that email).

  ```json 500 - Server Error theme={null}
  {
    "statusCode": 500,
    "success": false,
    "status": "server_failed",
    "message": "Server failed on KYC status"
  }
  ```
</ResponseExample>

### Response

<ResponseField name="data.status" type="string" required>
  Stored KYC status for the user.
</ResponseField>

<ResponseField name="data.approved" type="boolean" required>
  Whether the user is approved.
</ResponseField>

<ResponseField name="data.session_id" type="string">
  Current Didit session id when available.
</ResponseField>

<ResponseField name="data.session_status" type="string">
  Session status from the provider.
</ResponseField>

<ResponseField name="data.session_url" type="string">
  Hosted verification URL when available.
</ResponseField>

<ResponseField name="data.ip_info" type="array">
  Deduplicated IP / device summaries (country, VPN/Tor, data center flags, etc.).
</ResponseField>

<ResponseField name="data.is_blocklisted" type="boolean">
  `true` when document or liveness checks include a blocklisted match.
</ResponseField>