turingverify 0.2.0

Official Python SDK for the Turing Verify API

turingverify

Official Python SDK for the Turing Verify document verification API.

Install

pip install turingverify

Requires Python 3.9+. Depends only on httpx and pydantic.

Quickstart

from turingverify import TuringVerify

client = TuringVerify(api_key="tv_live_sk_...")

with open("diploma.pdf", "rb") as f:
    ver = client.verifications.create(file=f, filename="diploma.pdf")

print(ver.verdict, ver.confidence)
# → 'ACCEPT' 0.94

Async

import asyncio
from turingverify import AsyncTuringVerify

async def main():
    async with AsyncTuringVerify(api_key="tv_live_sk_...") as client:
        ver = await client.verifications.retrieve("ver_abc...")
        print(ver.verdict)

asyncio.run(main())

Verifying webhook signatures

from turingverify import verify_signature, SignatureVerificationError

@app.post("/hooks/turing-verify")
async def receive(request):
    body = await request.body()
    sig = request.headers["X-TuringVerify-Signature"]
    try:
        verify_signature(body, sig, SECRET, tolerance=300)
    except SignatureVerificationError:
        return 400, "bad signature"
    # ...process event

Errors

Every error inherits TuringVerifyError:

from turingverify import (
    TuringVerifyError,       # base class
    APIError,                # generic non-2xx
    AuthenticationError,     # 401
    InvalidRequestError,     # 400 / 422
    RateLimitError,          # 429 — exposes .retry_after
    IdempotencyConflictError,# 409
    SignatureVerificationError,  # webhook HMAC failed
)

Retry behavior

• 5xx, 429, and network errors retry with exponential backoff (+ jitter).
• Retry-After is honored when the server sends it.
• max_retries=3 by default — pass max_retries=0 to disable.

Idempotency

Every POST /v1/verifications call gets an automatic UUID4 Idempotency-Key header. Pass idempotency_key="..." to use your own. Replays within 24h return the cached response.

CLI

# Environment variables:
export TURING_VERIFY_API_KEY=tv_live_sk_...

turingverify verify path/to/diploma.pdf
turingverify tokens create --name ci-pipeline --env live
turingverify webhooks list
turingverify webhooks send-test whk_abc...
turingverify --json tokens list

License

MIT — see LICENSE.