Sphinx (v2)

Preview

SPHINX:v2 is in preview. The implementation of the Verification datablock 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 datablock 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.
`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 datablocks

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 datablocks

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

`Verification` datablock

The Verification datablock 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 datablocks​

Verdicts​

Output datablocks​

Verification datablock​

methods[].documentCheck​

Checks​