Python SDK

Introduction

reversecontact is the official Python client for the Reverse Contact API. You can call every API endpoint with typed models. The SDK handles safe retries, waits for asynchronous jobs, and pages through search results within a budget you set. Choose the synchronous client, ReverseContact, or the asynchronous client, AsyncReverseContact. Both have the same methods.

• Package: reversecontact on PyPI
• Source code and issues: github.com/visum-run/reversecontact-python
• License: Apache-2.0

The SDK needs Python 3.11 or later. These pages document reversecontact 0.3.0.

Install

pip install reversecontact

API key

Set RC_API_KEY or pass api_key to the client. Keep the key server-side. Follow Install and configure to set up your client.

First call

This lookup costs 2 credits when a person is found and nothing when no profile matches. With RC_API_KEY set:

from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.enrich.person(email="jane.doe@acme.com")
    if result is None:
        print("No confident match: nothing was charged")
    elif result.data and result.data.person:
        print(result.data.person.first_name, result.data.person.last_name)

First call explains the response fields, credit usage and request ids.

Endpoints and methods

Each endpoint page shows its call in the Python SDK tab of its code examples. For now, the List and Bulk enrichment examples are in Lists and Bulk enrichment instead.

Where to go next

• Install and configure
• First call
• client.enrich
• client.fetch
• client.search
• client.contact
• client.lists
• client.bulk
• client.jobs
• client.usage
• Async client
• Async jobs
• Lists and Bulk enrichment
• Search within a budget
• Filter values as constants
• Errors and retries
• Timeouts and cancellation
• Client options
• Without the SDK

Async client

Use AsyncReverseContact with await and async for, as shown in Async client.

Lookups that find nothing

Enrich and cached Fetch return None when no profile matches, at no credit cost. See how to handle lookups that find nothing.

Async jobs: live fetch, Find Email and Find Phone

Save job.id, then call job.wait() to poll for free. The default deadline is 30 minutes. Failed jobs raise JobFailedError. See the examples in Async jobs: live fetch, Find Email and Find Phone.

Webhook delivery instead of polling

Pass webhook_url and parse callbacks with parse_webhook_delivery, as shown in Webhook delivery.

Lists and Bulk enrichment

Lists and Bulk enrichment shows how to manage persistent Lists, run Bulk jobs, and read their results as they come or export them.

Search within a budget

Count for free, then cap paid results with the search iterator's required max_results argument. Follow the example in Search within a budget.

Filter values as constants

Use string enums for fixed search values or pass plain strings.

Errors and retries

The SDK retries per-minute rate limits and HTTP 500, 502, 503 and 504 up to four times. Daily limits, key credit limits, insufficient credits and other 4xx responses are not retried, except contact 409 IDEMPOTENCY_KEY_IN_USE. Read Errors and retries.

Safe retries on Find Email and Find Phone

Contact methods generate idempotency keys and reuse them on retries. See how this makes retries safe on Find Email and Find Phone.

Timeouts and cancellation

Timeouts and cancellation covers per-request timeouts, overall polling deadlines and cancelling local asyncio waits.

Client options

Configure connection pools, defaults and logging with Client options.

Without the SDK

To use an HTTPS client and the published OpenAPI specification, see Without the SDK.