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.

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:

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

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
  }
}

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"

Overview

Guides

Endpoint

Request

Examples

Responses

200 — Status retrieved

400 — Missing identifier

404 — Not found

500 — Server error

​Endpoint

​Request

​Examples

​Responses

​200 — Status retrieved

​400 — Missing identifier

​404 — Not found

​500 — Server error

​Related

Endpoint

Request

Examples

Responses

200 — Status retrieved

400 — Missing identifier

404 — Not found

500 — Server error

Related