Verify and decide

This page shows how to verify an ID using the SDK and how to interpret the result in a way that supports automated decisions.

The SDK does not change verification semantics. It exposes the same engine output returned by the /verify endpoint and adds helpers to reason about that output safely and consistently.

For the underlying verification operation and response structure, see Verify an ID.

Typical decision flow

A common integration follows these steps:

1. Receive an ID, and optionally infer its type.
2. Verify the ID using the engine.
3. Interpret the outcome and issues.
4. Decide whether to accept, reject, or flag the ID.

If you intend to verify multiple IDs in a batch, see Bulk verification for a more efficient execution pattern.

Verifying an ID with the SDK

1
import { createVerifyVatClient, Verifier } from '@verifyvat/sdk'
2

3
const client = createVerifyVatClient()
4
const verifier = new Verifier(client)
5

6
const verification = await verifier.verifyId({
7
    id: '914778271',
8
    type: 'no_orgnr',
9
})

1
from verifyvat_sdk import VerifyVatClient, Verifier
2

3
client = VerifyVatClient()
4
verifier = Verifier(client)
5

6
verification = verifier.verify_id(
7
    id="914778271",
8
    type="no_orgnr",
9
)
10
client.close()

At this point, verification contains the full output produced by the engine, equivalent to the REST API response data.

Interpreting the outcome

The engine always returns a structured result, even when the ID is invalid or unconfirmed.

Decisions should be based on the combination of overall outcome, reported issues, and registry evidence, rather than on the presence or absence of entity data alone.

The SDK exposes helpers that encapsulate the recommended interpretation rules.

Using decision helpers

The Verifier class provides helpers to extract meaningful signals from a verification result.

1
// continuing from above
2

3
const desc = verifier.describeVerification(verification)
4

5
// A selection of useful signals:
6
console.log('Is confirmed:', desc.isConfirmed)
7
console.log('Is invalid:', desc.isInvalid)
8
console.log('Is degraded:', desc.isDegraded)
9

10
console.log('Has partial coverage:', desc.hasPartialCoverage)
11
console.log('Has stale outcome:', desc.hasStaleOutcome)
12

13
console.log('Is review recommended:', desc.reviewRecommended)
14
console.log('Is retry recommended:', desc.retryRecommended)

1
# continuing from above
2

3
desc = verifier.describe_verification(verification)
4

5
# A selection of useful signals:
6
print('Is confirmed:', desc.isConfirmed)
7
print('Is invalid:', desc.isInvalid)
8
print('Is degraded:', desc.isDegraded)
9

10
print('Has partial coverage:', desc.hasPartialCoverage)
11
print('Has stale outcome:', desc.hasStaleOutcome)
12

13
print('Is review recommended:', desc.isReviewRecommended)
14
print('Is retry recommended:', desc.isRetryRecommended)

These helpers do not hide data.
They derive their signals directly from the verification output, using the same semantics described in the API documentation.

Making decisions safely

Once you have decision-grade signals, product logic becomes explicit and auditable. The SDK helpers encode opinionated interpretation rules, but you are free to granularly change the policy used to describe the verification result.

The default policy produces the following recommended decision signals:

Common patterns include:

• accepting only confirmed, non-stale results
• routing degraded cases to manual review
• retrying when registry outages are detected
• rejecting immediately on invalid syntax

The SDK helpers encode these principles so they can be applied consistently across a codebase.

Error handling behaviour

SDK methods return verification results for all domain-level outcomes. Only envelope-level failures, such as authentication errors or malformed requests, raise exceptions by default. If suppress-errors mode is enabled, exceptions are swallowed and replaced with tainted results that clearly signal upstream failure. This allows batch and pipeline processing to continue without interruption.