revenuebase-sdk 0.3.0

Python SDK for the Revenuebase Email Verification and Company Resolver API.

Revenuebase Python SDK

Python SDK for the Revenuebase API — email verification, contact resolution, organization resolution, and batch job management.

Requirements

• Python ≥ 3.8

Install

pip install revenuebase-sdk

Quickstart

from revenuebase_sdk import RevenuebaseClient

client = RevenuebaseClient(api_key="your-api-key")
# Or set REVENUEBASE_API_KEY in your environment and call RevenuebaseClient()

# Verify a single email
result = client.email.verify(email="[e-mail]")
print(result.status)  # "Valid", "Invalid", or "Unknown"

# With full metadata
result = client.email.verify(email="[e-mail]", metadata=True)
print(result.mx_record_present, result.email_provider)

# Check your credit balance
usage = client.account.balance()
print(usage.credits)

Authentication

Pass your API key via the api_key parameter or the REVENUEBASE_API_KEY environment variable. The key is sent as the x-key header on every request.

export REVENUEBASE_API_KEY="your-api-key"

Resources

account

Method	Description
balance()	Get your remaining credit balance.
rotate_api_key()	Generate a new API key (invalidates the previous one immediately).

contact

Method	Description
refresh_email(*, email)	Resolve an email to the person's current contact records. Returns a status of current, refresh, or no_match.

email

Method	Description
verify(*, email, metadata=False)	Verify a single email. Returns Valid, Invalid, or Unknown. Rate limited to 5 req/s.
batch_upload(*, file, filename, metadata=False)	Upload a .csv or .json file for async batch verification.

jobs

Method	Description
list()	List all active (queued or processing) batch jobs.
get(*, process_id)	Get the status of a batch job.
cancel(*, process_id)	Cancel a queued or in-progress batch job.
download(*, process_id)	Download the results of a completed job as bytes.

organization

Method	Description
resolve(*, company_name, result_count=3, ...)	Match an organization name to verified records using semantic search.
discover(*, keyword, result_count=1000, min_similarity_score=0, ...)	Discover organizations matching a keyword or description.

Both methods accept optional headquarter filters: headquarters_country, headquarters_state, headquarters_city, headquarters_street, headquarters_zip. discover also accepts min_similarity_score (0–0.95) — only results at or above this threshold are returned and charged.

Batch verification workflow

import time

# 1. Upload the file
with open("emails.csv", "rb") as f:
    job = client.email.batch_upload(file=f, filename="emails.csv")

print(f"Job {job.process_id} queued")

# 2. Poll until complete
while True:
    status = client.jobs.get(process_id=job.process_id)
    print(status.current_status)
    if status.current_status in ("COMPLETED", "ERROR", "CANCELLED"):
        break
    time.sleep(5)

# 3. Download results
if status.current_status == "COMPLETED":
    data = client.jobs.download(process_id=job.process_id)
    with open("results.csv", "wb") as f:
        f.write(data)

Organization resolution

# Match by name
result = client.organization.resolve(
    company_name="Stripe",
    result_count=3,
    headquarters_country="US",
)
for org in result.companies:
    print(org.company_name, org.similar_score, org.headquarters_city)

# Discover by keyword
result = client.organization.discover(
    keyword="enterprise cybersecurity SaaS",
    result_count=100,
    headquarters_country="US",
)

Contact resolution

Use this to detect when someone on your list has moved companies, so you can refresh stale contact data before reaching out.

result = client.contact.refresh_email(email="[e-mail]")

if result.status == "current":
    print("Still at the same company")
elif result.status == "refresh":
    for contact in result.contacts:
        print(contact.FULL_NAME_PER, contact.EMAIL_ADDRESS_PER, contact.COMPANY_NAME_ORG)
else:  # "no_match"
    print("No matching person found")

Each item in result.contacts is a Contact — one position held by the matched person. Field names are the raw source identifiers (_PER for person fields, _ORG for organization fields, e.g. FIRST_NAME_PER, JOB_TITLE_PER, COMPANY_NAME_ORG); any field may be None if the record doesn't carry it.

Async usage

import asyncio
from revenuebase_sdk import AsyncRevenuebaseClient

async def main():
    async with AsyncRevenuebaseClient(api_key="your-api-key") as client:
        result = await client.email.verify(email="[e-mail]")
        print(result.status)

asyncio.run(main())

Error handling

from revenuebase_sdk import (
    AuthenticationError,
    BadRequestError,
    RateLimitError,
    APIConnectionError,
)

try:
    result = client.email.verify(email="[e-mail]")
except AuthenticationError:
    print("Invalid API key")
except BadRequestError as e:
    print(f"Bad request: {e.message}")
except RateLimitError:
    print("Rate limited — slow down requests")
except APIConnectionError as e:
    print(f"Network error: {e.message}")

Per-request options

# Override timeout for a single call
result = (
    client
    .with_options(timeout=5.0, max_retries=0)
    .email.verify(email="[e-mail]")
)

Migrating from v1

The v1 API was retired on July 7, 2026 and is no longer supported by this SDK. client.v1 has been removed entirely.

v1 (removed)	v2 replacement
client.user_operations.get_credits()	client.account.balance()
client.user_operations.rotate_api_key()	client.account.rotate_api_key()
client.email_processing.validate_email(email=...)	client.email.verify(email=...)
client.email_processing.batch_upload(...)	client.email.batch_upload(...)
client.email_processing.get_batch_status(process_id=...)	client.jobs.get(process_id=...)
client.email_processing.list_queued()	client.jobs.list()
client.email_processing.cancel_batch(process_id=...)	client.jobs.cancel(process_id=...)
client.email_processing.download_batch(process_id=...)	client.jobs.download(process_id=...)
client.company_resolver.resolve(...)	client.organization.resolve(...)
client.company_resolver.discover(...)	client.organization.discover(...)

If you're upgrading from a version that still had client.v1, pin to revenuebase-sdk<0.3.0 until you've migrated.

Development

pip install -e ".[dev]"
pytest
mypy src
ruff check src