Sphinx (v2)

Preview

SPHINX:v2 is in preview. The implementation of the Verification data block is not yet finalized and may change. Use SPHINX:v1 for all production flows.

Agent-assisted or automated document-based identity verification via IDnow's Sphinx service

Verifies the end user's identity by routing the session to IDnow's Sphinx service, which performs document analysis through either a live video session with an agent (VideoIdent) or a fully automated process (AutoIdent). The service examines document security features, performs face matching and liveness detection, and optionally cross-checks identity data supplied by an upstream step. Results are returned as a unified Verification data block describing the checks applied and the assurance level achieved.

Key features

Agent-assisted verification (VideoIdent) — A trained IDnow agent guides the user through document capture and checks security features, face match, and liveness in a live session.
Automated verification (AutoIdent) — Fully AI-driven analysis of document authenticity, security features, face matching, and liveness without human involvement.
Pre-fill from upstream steps — Optional inputSources bindings allow identity data collected earlier in the flow to be forwarded to Sphinx for cross-checking.
Unified Verification datablock — Produces a structured record describing the checks performed, the provider, and whether the session completed, was canceled, or ended due to fraud.

Configuration

Parameter	Type	Required	Description
`config.live.shortname`	string	Yes	Sphinx shortname for the live environment. Provided by IDnow during onboarding.
`config.staging.shortname`	string	Yes	Sphinx shortname for the staging environment. Provided by IDnow during onboarding.
`handoff`	boolean	No	When `true`, redirects the player immediately when the identification enters a pending review state (`REVIEW_PENDING`, `CHECK_PENDING`, or `FRAUD_SUSPICION_PENDING`) and resumes polling in the background. Uses the session `redirectUrl` if configured; otherwise shows a submission-complete message. Default: `false`.
`webJourneyOnly`	boolean	No	When `true`, the redirect URL returned to the player is constructed as the Sphinx web journey URL (derived from the onboarding base URL, shortname, and identification ID) instead of the channel chooser redirect URL. Default: `false`.
`inputSources`	object	No	Maps upstream step IDs to data blocks forwarded to Sphinx. See Input mapping.
`inputSources.basicIdentity`	string	No	ID of an upstream step whose `BasicIdentity` output should be forwarded to Sphinx for identity data cross-checking.
`inputSources.extendedIdentity`	string	No	ID of an upstream step whose `ExtendedIdentity` output should be forwarded to Sphinx for identity data cross-checking.

Example

{
  "config": {
    "live": {
      "shortname": "acme-live"
    },
    "staging": {
      "shortname": "acme-staging"
    }
  },
  "inputSources": {
    "basicIdentity": "COLLECT_DATA"
  }
}

Input data blocks

Data block	Required	Description
`BasicIdentity`	No	Identity data forwarded to Sphinx when `inputSources.basicIdentity` is configured. Used for cross-checking against document data.
`ExtendedIdentity`	No	Extended identity data forwarded to Sphinx when `inputSources.extendedIdentity` is configured. Used for cross-checking against document data.

Verdicts

Verdict	Description
`verified`	The document was successfully processed and identity data was extracted. The Sphinx service accepted the result — either the automated or agent-assisted analysis passed.
`fraud_detected`	The document was identified as fraudulent. Identity data may have been extracted and is available for manual review.

Output data blocks

Verdict	Data blocks produced
`verified`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `DocumentImages`, `Verification`
`fraud_detected`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `DocumentImages`, `Verification`

`Verification` data block

The Verification data block produced by SPHINX:v2 contains the outcome and the checks applied during the Sphinx process.

Field	Type	Description
`status`	string	Verification status. One of: `verified`, `rejected`, `fraudDetected`, `canceled`, `aborted`, `error`.
`provider`	string	Always `"IDnow DocIDV"`.
`trustFramework`	string \| null	Always `null` for Sphinx processes.
`assuranceLevel`	string \| null	Always `null` for Sphinx processes.
`verifiedAt`	string	ISO 8601 timestamp at which the Sphinx process completed.
`verificationProcessId`	string \| null	Sphinx session or transaction reference.
`terminationReason`	object \| null	Present when the process ended before completion. Contains `code` (string) and `message` (string \| null).
`methods`	array	Verification methods applied. Contains a single `documentCheck` method object describing the checks performed.

`methods[].documentCheck`

Sphinx always produces exactly one method entry of type documentCheck.

Field	Type	Description
`type`	string	Always `"documentCheck"`.
`checks`	array	Techniques that failed during the process. Empty on `verified` outcomes. See below.
`evidence`	array	References to evidence artifacts (e.g. session recordings, analysis reports) stored in the Vault.

Checks

Checks are only present on non-verified outcomes. When Sphinx returns a reason code that maps to a specific technique, a single check entry is produced with outcome: failed. Sessions that complete successfully produce no check entries.

Technique	Reason codes (examples)	Description
`securityFeatures`	`ID_SECURITY_FEATURE`, `WARNING_DIGITAL_DOCUMENT`, `WARNING_FAKED_MANIPULATED_ID`, …	Physical or visual document security element failed.
`documentValidity`	`ID_BROKEN`, `ID_DAMAGED`, `ID_EXPIRED`, `ID_NOT_SUPPORTED`, `WARNING_FAKED_SPECIMEN`, …	Document format, integrity, or validity check failed.
`dataCrosscheck`	`ID_BLURRY`, `ID_DATA`, `ID_WRONG_SIDE`, `WARNING_MANIPULATED_DATA`, …	MRZ/OCR/VIZ reading or data consistency check failed.
`faceMatch`	`SELFIE_BLURRY`, `USER_OBSCURED`, `WARNING_SELFIE_DISGUISED`, …	Portrait-to-live-capture comparison failed.
`liveness`	`WARNING_SELFIE_NO_REAL_PERSON`, `WARNING_SELFIE_REAL_PERSON`	Live person detection failed.
`agentReview`	`WARNING_IDENTITY_THEFT`, `WARNING_FRAUD_OTHER`, `WARNING_MONEY_MULE`	Generic fraud or compliance conclusion raised during agent review.

Reason codes that describe process interruptions (USER_CANCELLATION_*, APP_CANCELLATION_*, TSP_*, PAY_*, IDENT_*) do not produce a check — they populate terminationReason only.

Testing

Before going live, it is important to verify that your integration handles the full range of identification outcomes correctly — from successful verifications to fraud detections, aborts, and review delays.

IDnow provides a Test-Robot service on the TEST environment that simulates the agent side of an identification automatically. This lets you trigger and observe different end-to-end scenarios — such as a happy path, a fraud case, or a canceled ident — and confirm that your application correctly receives and processes the results (e.g. via webhook or API response). Test-Robot is not a replacement for QA engineers, but a tool to validate your integration during development.

Two identification types are supported:

AutoIdent (AI) — Fully automated, app-based identification. See the AutoIdent Test-Robot documentation.
VideoIdent (VI) — Agent-assisted video identification. See the VideoIdent Test-Robot documentation.

Agent-assisted or automated document-based identity verification via IDnow's Sphinx service​

Key features​

Configuration​

Example​

Input data blocks​

Verdicts​

Output data blocks​

Verification data block​

methods[].documentCheck​

Checks​