Skip to main content
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.
The user must already have completed prepare or prepare-wallet and have a KYC session. If there is no record yet, you will receive a 404 response.

​
Endpoint

GET /kyc/status

​
Request

Provide email or wallet as a query parameter:
FieldTypeRequiredDescription
emailstringOne of email or walletSame email used across the email flow
walletstringOne of email or walletSame wallet used across the wallet flow

​
Examples

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

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

​
Responses

​
200 — Status retrieved

{
  "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
  }
}
FieldDescription
statusOverall KYC status stored for that user
approvedWhether the user is approved for KYC
session_idCurrent verification session identifier
session_statusStatus reported for the session
session_urlHosted flow URL when available
ip_infoSummarized IP / device context (deduplicated by IP)
is_blocklistedWhether 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"