# Custom Identity Verification

This guide shows how to structure a custom identity verification journey using four API endpoints:

- `POST /api/v2/liveness_check`
- `POST /api/v2/id_extract`
- `POST /api/v2/dvs/passport` (or other DVS endpoints depending on the document type)
- `POST /api/v2/likeness_check`


## Quick Start

The following is a typical orchestration for a custom identity verification flow that includes liveness, ID document OCR, ID document verification with DVS and face comparison:

1. Create a liveness check link.
2. Send the customer to that link and wait for completion.
3. Fetch the liveness result (including a probe image).
4. Collect identity document images in your app.
5. Run `id_extract` on the document images to get biographic data and the ID photo on the document.
6. Run a DVS check using the biographic data obtained from the ID document.
7. Compare `probe_image` vs extracted licence/passport `photo` using `likeness_check`.
8. Apply your business decision rules and store the outcome.

## 1) Liveness

Create a liveness check:

```http
POST /api/v2/liveness_check
```

Recommended request:

```json
{
  "return_url": "https://yourapp.example.com/verify/return",
  "webhook_url": "https://yourapp.example.com/webhooks/liveness",
  "link_valid_mins": 10,
  "threshold": 70,
  "audit_images": 0
}
```

You will receive:

- `token`
- `url` (send user here)
- `secret` (for webhook signature verification)

The token is a reference to the liveness session and is used to retrieve results.
Send the user to `url`.

The user will complete the liveness flow on our hosted UI. You will receive a webhook on completion or expiry, but you can also poll for results as described in the next step.


## 2) Retrieve liveness result safely

When the user returns to your app, you may receive `lc_token` in query params to help identify the session the user was using.
As it comes from the user, treat it as untrusted input.

Verify the results from the server-side by calling:

```http
GET /api/v2/liveness_check?token={token}
```

Use your server-stored liveness token from session creation when calling GET result.

Possible outcomes:

- `202`: still `pending` or `in_progress` (keep polling)
- `200`: complete with `result`
- `410`: expired

Use the response `result` fields:

- `passed`
- `confidence`
- `threshold`
- `image` (probe image; short-lived)

For this workflow, continue only when:

- `passed = true`
- `image` exists (probe image required for face match)

## 3) Collect ID document images

In your app, ask the user for images of the identity document. We are able to perform OCR on Australian passport, driver licences and Medicare cards.

For a licence, you typically need the front and back images to extract all required fields. Medicare cards only need the front image. For a passport, the an image of the photo page is required.:

- `document_photo` (front)
- `document_back` (back - only for licences)

Then call:

```http
POST /api/v2/id_extract
```

Example request for a driver licence:

```json
{
  "document_type": "licence",
  "document_photo": "data:image/jpeg;base64,...",
  "document_back": "data:image/jpeg;base64,..."
}
```

Success (`200`) returns extracted fields in `result`, including:

- Biographic fields (`first_name`, `last_name`, `birth_date`, etc.)
- `photo` (cropped face from the document, extracted during OCR)

If `photo` is missing or extraction fails, ask for better images and retry.

## 4) Run DVS check
Confirm the biographical data with the user and, with their consent, use the data to run a DVS check:

```http
POST /api/v2/dvs/passport
```
Example request:

```json
{
    "first_name": "ED VIRGIL",
    "last_name": "LEUSCHKE",
    "birth_date": "1993-03-23",
    "travel_document_number": "M1000000", 
    "consent": true
}
```

## 5) Run face similarity check
If you are working with a licence or passport, you will have a photo extracted from the document. You can compare this with the liveness probe image to confirm the person in front of the camera is the same as the person on the ID document.

Compare the liveness probe image with the extracted ID document photo using `likeness_check`:

```http
POST /api/v2/likeness_check
```

Example request:

```json
{
  "photo": "data:image/jpeg;base64,...", 
  "probe_image": "data:image/jpeg;base64,...",
  "similarity_threshold": 80
}
```

`200` response includes:

- `result.similarity`
- `result.threshold`
- `result.biometric_passed`

## 6) Make a final decision

A common decision policy:

- Liveness must pass
- Likeness must pass
- DVS Identity Validation must pass

Any significant editing from the user of the biographic data extracted from the ID document should be treated as a risk signal and may require additional review or rejection.

## 7) Security, privacy and consent (recommended)

This workflow processes sensitive identity and biometric data (for example, liveness probe images and document photos). You should:

- Obtain clear user consent before running DVS and biometric checks.
- Use HTTPS/TLS for all API calls and webhook endpoints.
- Verify webhook signatures before trusting webhook events.
- Restrict access to identity data to only the systems and staff that need it.
- Keep only the minimum data needed for compliance and audit requirements, then securely delete data you no longer need.
- Avoid storing raw base64 images long term unless required by your regulatory obligations.