> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verisecid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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`.

```http theme={null}
Authorization: Bearer pb-YourPublicKey
```

## Create a hosted session

Optional body lets you add a return link and metadata to track your users.

```bash theme={null}
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):

```json theme={null}
{
  "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.

<Tip>
  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.
</Tip>

## Retrieve a session

```bash theme={null}
curl -X GET "https://api.verisecid.com/v1/kyc/sessions/SESSION_ID" \
  -H "Authorization: Bearer sc-YourSecretKey"
```

Example response:

```json theme={null}
{
  "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" }`

<CardGroup cols={2}>
  <Card title="Development" icon="wrench" href="/development">
    Environment variables and security model.
  </Card>

  <Card title="API reference" icon="terminal" href="/api-reference/introduction">
    Endpoint details and examples.
  </Card>
</CardGroup>