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.

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, construct_event

# Flask
event = construct_event(request.get_data(), request.headers, secret)
delivery_id = request.headers.get(WEBHOOK_DELIVERY_ID_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, so record it and ignore repeats. 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.

License

MIT

Metadata

Release files for vendorval-sdk 0.10.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.10.0
File Size Uploaded Provenance Actions
vendorval_sdk-0.10.0.tar.gz 47.9 kB With provenance Details for vendorval_sdk-0.10.0.tar.gz

Built distribution (wheel)

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

Total release size: 85.4 kB

Release files / vendorval_sdk-0.10.0.tar.gz

Download URL vendorval_sdk-0.10.0.tar.gz
Size 47.9 kB
Tags Source
SHA-256 checksum
How to use checksums
94486a3ee0587ef8d90ebbfb5ce29ea918c7b0d11aada3846cc0004c9bcf88f0
BLAKE2b-256 checksum
How to use checksums
0e1338e74a5ce57d793d9dd5801dc48a9906e9cc10436612b54c428f4b0f68e2
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 Oct 26, 2026.

Transparency log

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

Download URL vendorval_sdk-0.10.0-py3-none-any.whl
Size 37.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
df84ec2dcba8f63912753111d2e79ed4f38ea94839c4ede1ed808492ae9aff34
BLAKE2b-256 checksum
How to use checksums
9415d1946b3bd86ac8f612a84d94dd0572b9c91311a077b80a0cf74da66ec145
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 Oct 26, 2026.

Transparency log

Security for vendorval-sdk 0.10.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.10.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 Oct 26, 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