API Reference

Base URL: https://veriflow.jarvis.kodecast.com/api/v1 · Auth: Authorization: Bearer vf_sk_…

Create a verification

curl -X POST https://veriflow.jarvis.kodecast.com/api/v1/verifications \
  -H "Authorization: Bearer vf_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_ref": "user-42",
    "ttl_minutes": 60
  }'

Response 201:

{
  "id": "0192c1a0-...",
  "object": "verification",
  "status": "pending",
  "subject_ref": "user-42",
  "hosted_flow_url": "https://your-domain.com/v/abc123...",
  "session_token": "abc123...",
  "expires_at": "2026-08-17T22:00:00+00:00"
}

Field	Type	Notes
`subject_ref`	string?	Your identifier for the user — echoed back in webhooks.
`ttl_minutes`	int?	5–1440. Default 60. Session expires after this.

Retrieve a verification

curl https://veriflow.jarvis.kodecast.com/api/v1/verifications/{id} \
  -H "Authorization: Bearer vf_sk_YOUR_KEY"

Returns full status, normalized checks (document / liveness / face_match) and extracted identity fields when available.

List verifications

curl "https://veriflow.jarvis.kodecast.com/api/v1/verifications?status=approved&per_page=20" \
  -H "Authorization: Bearer vf_sk_YOUR_KEY"

Cursor-paginated. Filter by status and subject_ref.

Cancel a verification

curl -X POST https://veriflow.jarvis.kodecast.com/api/v1/verifications/{id}/cancel \
  -H "Authorization: Bearer vf_sk_YOUR_KEY"

Only non-final verifications can be cancelled (409 otherwise).

Scopes

Scope	Allows
`verifications:read`	GET endpoints
`verifications:write`	POST create / cancel
`webhooks:manage`	Webhook endpoint CRUD (reserved)

Errors

{ "error": { "message": "API key missing scope [verifications:write]." } }

401 bad key · 403 scope/IP denied · 404 not found · 409 conflict · 429 rate limited