Skip to main content

vendorval-sdk

Official Python SDK for the VendorVal API.

pip install vendorval-sdk

Requires Python >=3.11. Set VENDORVAL_API_KEY before running these examples; identifiers below are illustrative.

Quick start

from vendorval_sdk import Vendorval

client = Vendorval()  # reads VENDORVAL_API_KEY from env

# 1) Look up an entity by identifier
lookup = client.entities.lookup(identifiers={"uei": "ABCD12345678"})
if lookup.match == "not_found":
    raise SystemExit("entity not in registry")

# 2) Run a verification and wait for the terminal result
bundle = client.verifications.create_and_wait(
    identifiers=[{"type": "uei", "value": "ABCD12345678"}],
    legal_name="Acme Federal Services LLC",
    checks=["sam_registration"],
    mode="cached",
)
print(bundle.verification.overall_result)

Async

import asyncio
from vendorval_sdk import AsyncVendorval

async def main() -> None:
    async with AsyncVendorval() as client:
        result = await client.entities.lookup(identifiers={"uei": "ABCD12345678"})
        print(result.match)

asyncio.run(main())

Configuration

client = Vendorval(
    api_key="vv_live_…",
    base_url="https://api.vendorval.com",
    timeout=30.0,                 # seconds, default 60
    max_retries=2,                # default 2
)

API keys are prefixed vv_test_ (sandbox), vv_live_ (production) or vv_mcp_ (keys issued for MCP clients). The client checks the prefix and raises VendorvalError with code="invalid_api_key_prefix" on anything else, before any request is sent. Whitespace around the key is ignored.

The base URL must use https://, except for localhost. For a trusted private network, pass allow_insecure_base_url=True.

Errors

from vendorval_sdk import RateLimitError, ConflictError, ValidationError

try:
    client.verifications.create(...)
except RateLimitError as err:
    print("rate limited, retry after", err.retry_after, "seconds")
except ConflictError as err:
    print("ambiguous match", err.candidates)

All errors carry request_id, status, code, type, message.

Pagination

List methods return a page. Iterating it walks every page: while the API reports has_more, the SDK requests the next page at the following offset.

for monitor in client.monitors.list(limit=50):
    print(monitor["id"])

monitors = client.monitors.list().all()  # every item, as a list

The async client returns an AsyncPage: use async for monitor in await client.monitors.list() and await page.all(). For one page at a time, read page.data and page.has_more, and call page.next_page() (it returns None after the last page).

Monitors and webhooks

A monitor re-runs checks on an entity at a fixed frequency and POSTs each detected change to its webhook_url. Every monitor has its own signing secret, returned once when the monitor is created:

monitor = client.monitors.create(
    entity_id="ent_123",
    checks=["sam_exclusion", "sanctions_screening"],
    frequency="daily",  # "daily" | "weekly" | "monthly"
    webhook_url="https://example.com/webhooks/vendorval",
)
# Store this. It is not returned again; client.monitors.rotate_secret(id) issues a new one.
save_secret(monitor["id"], monitor["webhook_secret"])

Verify each delivery with construct_event, passing the raw request body, the request headers and that monitor's secret:

from vendorval_sdk import (
    WEBHOOK_DELIVERY_ID_HEADER,
    WEBHOOK_SIGNATURE_HEADER,
    construct_event,
)

# Flask
event = construct_event(request.get_data(), request.headers, secret)
delivery_id = request.headers.get(WEBHOOK_DELIVERY_ID_HEADER)
signature = request.headers.get(WEBHOOK_SIGNATURE_HEADER)

construct_event checks the X-ETP-Signature header (sha256=<hex>, an HMAC-SHA256 of <X-ETP-Timestamp>.<raw body>) in constant time, and rejects deliveries whose X-ETP-Timestamp is more than 300 seconds from now (tolerance= changes that). It raises VendorvalError with type="webhook_error" on any failure. Use the raw body: re-serializing parsed JSON changes the bytes and the signature will not match.

Deliveries are at-least-once. Retries of the same delivery reuse X-ETP-Delivery-Id but are signed again, and the delivery id is not covered by the signature. Keep processed signatures (compared in lowercase) and bind each processed delivery id to a SHA-256 digest of its verified raw body. A known signature is a repeat; a re-signed retry is a repeat only when both its id and body digest match a completed delivery. Record that retry signature too. An unsigned id with a different body must not suppress an event or mark its signature as processed. Keep this state in durable storage with an appropriate retention period; see the webhook-handler example. Each monitoring.changes_detected delivery carries one change in event["data"]["changes"], and event["data"]["monitor_id"] tells you which monitor's secret to use.

This cache is best-effort. Two distinct deliveries with identical raw bodies signed in the same second have identical signatures, even when their unsigned delivery IDs differ. Distinguishing those deliveries requires the sender to include a unique event ID in the signed payload; an unsigned header cannot provide that guarantee.

License

MIT

Metadata

Release files for vendorval-sdk 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vendorval-sdk 0.11.0
File Size Uploaded Provenance Actions
vendorval_sdk-0.11.0.tar.gz 52.2 kB With provenance Details for vendorval_sdk-0.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vendorval-sdk 0.11.0
File Interpreter ABI Platform Actions
vendorval_sdk-0.11.0-py3-none-any.whl Python 3 none any Details for vendorval_sdk-0.11.0-py3-none-any.whl

Total release size: 91.2 kB

Release files / vendorval_sdk-0.11.0.tar.gz

Download URL vendorval_sdk-0.11.0.tar.gz
Size 52.2 kB
Tags Source
SHA-256 checksum
How to use checksums
f7e2fa39768ce657ffdba55a9f1226c87aca781d8d7f7c770bc7127899657ed9
BLAKE2b-256 checksum
How to use checksums
6e0d8a226461d2245c41699d8aec8bd6fcafd4519b9f740d5927370ba035affb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / vendorval_sdk-0.11.0-py3-none-any.whl

Download URL vendorval_sdk-0.11.0-py3-none-any.whl
Size 39.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7a7bd0695171a29b13f833f7f002a41636e8a4bd30f28f4f1b13a6716fed178a
BLAKE2b-256 checksum
How to use checksums
d94ad97254d35e84e1fdf5fab6e51b8b7ac80d3ae18994159b3e94cd75767738
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for vendorval-sdk 0.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vendorval_sdk-0.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page