Sessions

Retrieve a session

Returns a session by ID.

GET /api/v1/sessions/{session_id}

Returns a session: where it's got to, what was captured, and the decision once there is one. You can only retrieve your own sessions.

link Authorization

Authorization string header required

Your secret key, as Bearer kyc_live_.... The key needs the sessions:read scope.

link Path

session_id string path required

The session's id, from when you created it.

link Response

Returns 200 OK with the session object.

lightbulb

Polling

If you poll, wait at least 10 seconds between requests and stop once the status is clear, rejected, expired or cancelled. A consider session waits for your team's review, which can take hours: don't poll it, wait for its session.completed webhook.

link Errors

Status	Code	When
`401`	`AUTHENTICATION_ERROR`	Missing, invalid or revoked key
`403`	`AUTHORIZATION_ERROR`	The key doesn't have the `sessions:read` scope
`404`	`NOT_FOUND`	No such session on your account

cURL

curl https://www.kaywhysee.com/api/v1/sessions/$SESSION_ID \
  -H "Authorization: Bearer $KAYWHYSEE_API_KEY"

Node.js

const response = await fetch(
  `https://www.kaywhysee.com/api/v1/sessions/${sessionId}`,
  { headers: { Authorization: `Bearer ${process.env.KAYWHYSEE_API_KEY}` } },
);
const session = await response.json();

Python

session = requests.get(
    f"https://www.kaywhysee.com/api/v1/sessions/{session_id}",
    headers={"Authorization": f"Bearer {os.environ['KAYWHYSEE_API_KEY']}"},
    timeout=10,
).json()

200

{
  "id": "a841ce23-0c9d-42a4-ba95-3e7e17a1407b",
  "reference": "user_1042",
  "status": "submitted",
  "outcome": null,
  "reasons": [],
  "reviewed": false,
  "review": null,
  "retry_session_id": null,
  "retry_of": null,
  "checks": {},
  "document_type": "passport",
  "document_country": "GBR",
  "captures": {
    "doc_front": 1,
    "selfie_clip": 1,
    "selfie_keyframe": 3
  },
  "created_at": "2026-10-15T12:10:11Z",
  "expires_at": "2026-10-16T12:10:11Z",
  "submitted_at": "2026-10-15T12:14:52Z",
  "decided_at": null
}

404

{
  "success": false,
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Session not found: 4f1c..."
  }
}

Was this page helpful?