Skip to main content
title: “Quickstart” description: “Understand the hosted KYC flow and how to integrate it”

​
KYC in one minute

  • Create a session: You call POST /v1/kyc/sessions with your Bearer public key. You receive a sessionId and a verificationUrl.
  • Send your user: Redirect or link your user to the verificationUrl to complete the hosted verification flow.
  • Check status: You can GET /v1/kyc/sessions/{sessionId} to verify ownership and see the current status.

​
Authentication

Use your public API key in the Authorization header. Public keys map to workspaces in Firestore at workspaces.apiPublicKey. 
Authorization: Bearer pb-YourPublicKey

​
Create a hosted session

Optional body lets you add a return link and metadata to track your users. 
curl -X POST "https://api.verisecid.com/v1/kyc/sessions" \
  -H "Authorization: Bearer pb-YourPublicKey" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://yourapp.com/kyc/return",
    "metadata": { "customerId": "12345" },
    "firstName": "Jane",
    "lastName": "Doe"
  }'
Successful response (201): 
{
  "sessionId": "<session-id>",
  "verificationUrl": "https://<host>/verify/<session-id>",
  "workspaceId": "<workspace-id>",
  "userId": "<uid>",
  "status": "not_started",
  "createdAt": "2025-08-09T10:00:00.000Z",
  "applicantFirstName": "Jane",
  "applicantLastName": "Doe"
}

​
Send the user to verify

Open the verificationUrl in a browser or in-app webview. The hosted UI captures documents and face images, then invokes a server action to produce a structured verdict.
The API does not expose this verdict directly; persist results in your backend if needed.
When the session status is processing, the Verify UI hides the QR code and action buttons and displays “Running on another device.” This prevents duplicate flows if the user already opened the link elsewhere.

​
Retrieve a session

curl -X GET "https://api.verisecid.com/v1/kyc/sessions/SESSION_ID" \
  -H "Authorization: Bearer sc-YourSecretKey"
Example response: 
{
  "sessionId": "<session-id>",
  "workspaceId": "<workspace-id>",
  "userId": "<uid>",
  "status": "not_started",
  "redirectUrl": null,
  "metadata": { "customerId": "12345" },
  "createdAt": "2025-08-09T10:00:00.000Z",
  "updatedAt": "2025-08-09T10:05:00.000Z",
  "verificationUrl": "https://<host>/verify/<session-id>"
}
Authorization rules:
  • The requesting user must be the session owner (userId) OR the owner of the associated workspaceId.

​
Status lifecycle

  • Initial: not_started
  • Typical progression: not_started → processing → completed (or failed)
  • The Verify UI prevents reuse when status === "completed".

​
Errors

  • 401 { "error": "missing_authorization" } when header is absent
  • 401 { "error": "invalid_credentials" } when public key is invalid
  • 403 { "error": "forbidden" } when the user does not own the session/workspace
  • 404 { "error": "not_found" } when session does not exist
  • 500 { "error": "internal_error", "message": "..." } on server error

​
Hosts and CORS

  • Base host: https://api.verisecid.com
  • Served only on allowed hosts: api.verisecid.com, localhost, 127.0.0.1
  • Override with env var: API_ALLOWED_HOSTS=api.verisecid.com,localhost,127.0.0.1
  • Disallowed hosts return 404 with { "error": "invalid_host" }

Development

Environment variables and security model.

API reference

Endpoint details and examples.