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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.