# ID Pass - IDSP mode

In IDSP mode (`document_verification: idsp`), Global Data returns an **identity opinion** - a single valid / not valid assessment produced by the combined checks of Global Data's Document Validation System and DVS. Global Data runs the document verification on your behalf and provides you with an identity opinion on whether the documents are valid or not.

This mode is intended for customers who are not registered with DVS but need a compliant identity verification service. Global Data acts as an Identity Service Provider (IDSP) on your behalf, and the identity opinion returned is Global Data's own assessment, not a DVS response.

## Requirements

- Liveness detection must be enabled on every ID Pass (`check_liveness` set to `true`). This is mandatory in IDSP mode - it ensures the identity opinion is based on multiple independent identity checks (liveness, biometric face match where a photo ID is supplied, and document verification).
- Your account must be enrolled as an IDSP Service Client. Contact your Global Data account manager to arrange enrolment.
- No DVS Identity (OAC) is required on your account.

## Quick start

### 1. Create an ID Pass

Call `POST /idpass/register` with `document_verification` set to `idsp` and `check_liveness` set to `true`.

Example request:

```json
{
  "document_verification": "idsp",
  "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` carries Global Data's identity opinion: `passed` (valid) or `failed` (not valid). 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": "idsp",
    "liveness_result": {
      "validated": true,
      "confidence": "99.811",
      "threshold": 70,
      "liveness_attempts": 1,
      "bounding_box": { "...": "..." }
    },
    "document_1_result": {
      "document_type": "passport",
      "validated_fields": {
        "first_name": "John",
        "middle_name": null,
        "last_name": "Smith",
        "date_of_birth": "1990-03-21"
      },
      "biographic_validated": true,
      "changes": {},
      "biometric_validated": true,
      "biometric_similarity": "99.804",
      "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 IDSP mode:

- `verification_status` - this is Global Data's identity opinion: `passed` (valid) or `failed` (not valid).
- `verification_description` - human-readable reason.
- `validation_summary.document_N_result.biographic_validated` - whether the document passed Global Data's combined Document Validation System and DVS checks.
- `validation_summary.document_N_result.biometric_validated` - whether the biometric face match passed for that document.

DVS result codes, DVS error codes, DVS request identifiers, and the OAC used are not available in the API response.

#### Opting in to the per-document detail

To see the per-document verification boolean, pass `return_documents: true` on the details request. The response then also contains a `documents` object with a per-document `validation_result`:

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

Key `validation_result` fields for IDSP mode:

- `strategy` - `idsp`
- `verification_passed` - boolean (valid / not valid) for that document
- `checked_at` - timestamp of the validation

## Sandbox testing

In sandbox, no real DVS calls are made and no fees are charged. Uploading a [DVS sample document](/docs/guides/dvs/sample-documents) produces a predictable identity opinion:

- Sample documents that pass all checks → `verification_status: "passed"` (identity opinion is valid)
- Sample documents that fail any check → `verification_status: "failed"` (identity opinion is not valid)

See [Sandbox testing](/docs/guides/idpass/id-pass-overview#sandbox-testing) in the ID Pass Overview for the full picture.