SDK overview

The official SDKs provide a typed, idiomatic way to interact with the engine from application code.

They expose the same capabilities as the REST API and add helpers to reason about results, interpret outcomes, and work with the engine’s data model more effectively.

If your language is supported, the SDK is the recommended integration surface.
If not, the REST API remains fully supported and can be used directly.

Installation

The SDKs are distributed through standard package managers.

1
# JavaScript / TypeScript
2
npm install @verifyvat/sdk
3

4
# Python
5
pip install verifyvat-sdk

Configuration and authentication

The SDKs use the same API key mechanism as the REST API.

By default, clients automatically read configuration from environment variables and work out of the box when these are present.

1
VERIFYVAT_API_KEY=your_api_key_here
2
# Optional override for custom deployments
3
# VERIFYVAT_BASE_URL=https://api.verifyvat.com

You can also provide configuration explicitly when creating a client.
Both approaches are equivalent at runtime.

Authentication semantics are identical to the REST API.
See Authentication for details on key management and rotation.

What the SDK gives you

The SDK provides two complementary layers:

1. Typed access to API responses

All API endpoints are exposed through typed helpers that:

• construct requests correctly
• handle authentication automatically
• return structured data matching the documented API responses

At this level, the data returned is the same data you would receive when calling the REST endpoint directly.

2. Helpers to reason about results

On top of raw responses, the SDK provides helpers that make it easier to work with the engine’s output, for example:

• interpreting verification outcomes and issues
• selecting relevant identifiers, names, or registrations
• building computed views over coverage and registry metadata
• handling partial, degraded, or cached results consistently

These helpers never change the underlying data.
They operate purely on the API response.

Object-oriented and functional access

All SDK features are exposed in two equivalent forms:

• Object-oriented classes, like Verifier or TypeInferrer, that encapsulate related operations and state
• Pure helper functions, like verifyId(client, params) or inferIdType(client, params), that can be used without instantiating classes

Both styles are interchangeable.
You can mix them freely depending on your preferences and codebase style.

Error handling and envelopes

The SDK always returns unwrapped responses.

• The API response envelope is removed.
• Domain data is returned directly.

Only envelope-level errors (authentication failures, malformed requests, rate limits) raise exceptions by default.

Domain-level outcomes, such as an invalid identifier or an unconfirmed verification, are returned as structured results, not thrown as errors.

This mirrors how the engine itself behaves.

Suppress-errors mode

The SDK supports a suppress-errors mode.

When enabled:

• errors that would normally raise an exception are swallowed
• a synthetic, tainted response is returned instead
• the response clearly signals that an error occurred upstream

This is useful for batch processing, pipelines, or long-running jobs where partial failure should not interrupt execution.

Source code

The SDKs are open source and distributed under the MIT license. They are developed and maintained alongside the API. You can browse the source code and sample projects at our official GitHub repository.

The repository includes implementation details, runnable examples, and advanced configuration options.