# ID Pass - Basic mode

Basic mode (`document_verification: basic`) performs format and checksum validation on the supplied document fields but does not perform any external verification. No DVS call is made, in either live or sandbox.

This mode is useful when you need OCR extraction, liveness, and biometric face match but intend to perform document verification yourself, or when DVS verification is not required for your use case.

## Requirements

- No DVS Identity or special enrolment is required.

## Quick start

### 1. Create an ID Pass

Call `POST /idpass/register` with `document_verification` set to `basic` and the documents you want to collect. Optionally enable the liveness and biometric face match checks via `check_liveness`.

Example request:

```json
{
  "document_verification": "basic",
  "check_liveness": true,
  "document_1_allowed_types": ["licence", "passport"],
  "document_2_allowed_types": ["licence", "passport", "medicare"],
  "webhook_url": "https://example.com/webhooks/idpass"
}
```

The response contains the `id`, the `link` to send to your customer, and a `cipher_key` for decrypting the results later:

```json
{
  "id": "19517924-94f0-4000-8e02-afba96ad5101",
  "link": "https://idpass.example.com/fe4291ca-d831-4760-96df-c9cb03b3cd95",
  "cipher_key": "IHm81bkcMsTL7J1ilxhDNE59+p5OQkvUJ3mZQhlUNHA="
}
```

See the [ID Pass API Reference](/docs/reference#id-pass) for all available request options.

### 2. Send the link to your customer

Provide the `link` to your customer by SMS, email, or by redirecting them from your application. See [What your customer experiences](/docs/guides/idpass/id-pass-overview#what-your-customer-experiences) for what they will see.

### 3. Track progress (optional)

If you supplied a `webhook_url` when creating the ID Pass, Global Data will POST a small payload to your endpoint each time the status changes:

```json
{
  "id": "19517924-94f0-4000-8e02-afba96ad5101",
  "status": "complete"
}
```

See the [Webhooks](/docs/guides/idpass/id-pass-overview#webhooks) section of the overview for supported events.

### 4. Retrieve results

Once the ID Pass status is `complete`, call `GET /idpass/details/{id}` with the `cipher_key` to retrieve the full result.

The top-level `verification_status` is `passed` when all documents pass format validation and cross-document identity data is consistent, `failed` otherwise. The default response also includes a decrypted `validation_summary` with strategy-agnostic per-document results:

```json
{
  "message": "Ok",
  "id": "19517924-94f0-4000-8e02-afba96ad5101",
  "status": "complete",
  "verification_status": "passed",
  "verification_description": "The identity was verified successfully",
  "config": { "...": "..." },
  "created_at": "2026-04-16T04:28:53+00:00",
  "consent_given_at": "2026-04-16T04:29:00+00:00",
  "consent_text": "...",
  "completed_at": "2026-04-16T04:29:30+00:00",
  "ip_address": "203.22.251.3",
  "validation_summary": {
    "document_verification": "basic",
    "liveness_result": {
      "validated": true,
      "confidence": "99.811",
      "threshold": 70,
      "liveness_attempts": 1,
      "bounding_box": { "...": "..." }
    },
    "document_1_result": {
      "document_type": "licence",
      "validated_fields": {
        "first_name": "John",
        "last_name": "Smith",
        "date_of_birth": "1990-03-21"
      },
      "biographic_validated": true,
      "changes": {},
      "biometric_validated": true,
      "biometric_similarity": "98.876",
      "biometric_threshold": 80
    },
    "verified_identity": {
      "first_name": "John",
      "middle_name": null,
      "last_name": "Smith",
      "date_of_birth": "1990-03-21"
    },
    "requested_identity_mismatch": false
  }
}
```

Key signals in Basic mode:

- `verification_status` - `passed` or `failed` for the overall ID Pass.
- `verification_description` - human-readable reason.
- `validation_summary.document_N_result.biographic_validated` - whether the document's fields passed format and checksum validation.
- `validation_summary.document_N_result.biometric_validated` - whether the biometric face match passed for that document.

#### Opting in to the per-field validation errors

To see the per-field validation errors for a failed document, pass `return_documents: true` on the details request. The response then also contains a `documents` object with a per-document `validation_result`. When validation passes:

```json
{
  "...": "...top-level fields as above...",
  "documents": {
    "document_1": {
      "document_type": "licence",
      "document_number": 1,
      "ocr_status": "complete",
      "ocr_attempts": 1,
      "validation_status": "complete",
      "validation_result": {
        "strategy": "basic",
        "basic_validation_passed": true,
        "errors": {},
        "checked_at": "2026-04-16 04:28:53"
      },
      "validation_attempts": 1,
      "biometric_result": {
        "passed": true,
        "threshold": 80,
        "similarity": 98.8764,
        "face_occluded": false
      },
      "ocr_data": { "...": "..." },
      "validation_data": { "...": "..." }
    }
  }
}
```

When validation fails, `errors` contains per-field messages:

```json
{
  "verification_status": "failed",
  "verification_description": "Document 1 failed format validation",
  "documents": {
    "document_1": {
      "document_type": "licence",
      "document_number": 1,
      "validation_status": "complete",
      "validation_result": {
        "strategy": "basic",
        "basic_validation_passed": false,
        "errors": {
          "card_number": ["The VIC licence card number must be 8 or 10 digits."]
        },
        "checked_at": "2026-04-16 04:28:53"
      }
    }
  }
}
```

Key `validation_result` fields for Basic mode:

- `strategy` - `basic`
- `basic_validation_passed` - boolean
- `errors` - per-field validation errors; empty object when validation passed
- `checked_at` - timestamp of the validation

## Sandbox testing

No DVS call is made in sandbox (or live) in Basic mode. Uploading a [DVS sample document](/docs/guides/dvs/sample-documents) produces a passing format validation (`basic_validation_passed: true` when you opt in via `return_documents: true`). Any other input is validated against the normal document format rules and passes or fails on its own merits. See [Sandbox testing](/docs/guides/idpass/id-pass-overview#sandbox-testing) in the ID Pass Overview for the full picture.