> ## 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.

# Getting status

Use **get status** to drive loading states in your app, refresh after the user returns from the hosted flow, or periodically poll until verification reaches a final outcome.

<Info>
  The user must already have completed [prepare](/prepare) or [prepare-wallet](/prepare-wallet) and have a KYC session. If there is no record yet, you will receive a **404** response.
</Info>

***

## Endpoint

```shellscript theme={null}
GET /kyc/status
```

***

## Request

Provide **email** or **wallet** as a query parameter:

| Field    | Type   | Required               | Description                             |
| -------- | ------ | ---------------------- | --------------------------------------- |
| `email`  | string | One of email or wallet | Same email used across the email flow   |
| `wallet` | string | One of email or wallet | Same wallet used across the wallet flow |

### Examples

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

```shellscript theme={null}
curl --request GET \
  --url 'https://api.starkfi.io/kyc/status?wallet=FmTGYpzX27fDqaiytXUdFVaphC5o68G61Q3uhVM2d8bm' \
  --header 'x-api-key: <api_key>'
```

***

## Responses

### 200 — Status retrieved

```json 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": [
      {
        "ip_address": "string",
        "ip_country": "string",
        "ip_state": "string",
        "ip_city": "string",
        "platform": "string",
        "device_brand": "string",
        "device_model": "string",
        "is_vpn_or_tor": false,
        "is_data_center": false
      }
    ],
    "is_blocklisted": false
  }
}
```

| Field            | Description                                                          |
| ---------------- | -------------------------------------------------------------------- |
| `status`         | Overall KYC status stored for that user                              |
| `approved`       | Whether the user is approved for KYC                                 |
| `session_id`     | Current verification session identifier                              |
| `session_status` | Status reported for the session                                      |
| `session_url`    | Hosted flow URL when available                                       |
| `ip_info`        | Summarized IP / device context (deduplicated by IP)                  |
| `is_blocklisted` | Whether blocklist signals were raised in document or liveness checks |

### 400 — Missing identifier

`status`: `missing_params` — `"email or wallet is required"`

### 404 — Not found

No KYC record or session exists for the given email or wallet.

### 500 — Server error

`status`: `server_failed` — `"Server failed on KYC status"`

***

## Related

* [Create KYC session](/create-session)
* [Getting started](/getting-started)