client.bulk

Start Bulk enrichment jobs, follow progress, browse job history, read results as they come and download them.

Calling conventions

Examples assume RC_API_KEY is set. Replace example ids with ids returned by your own requests. Signatures show the published 0.3.0 synchronous methods. Use the same arguments with the Python async client.

models refers to reversecontact.types. NOT_GIVEN and NotGiven are the SDK's internal markers for omitted arguments. Leave these arguments out of your calls. For API body parameters, passing None sends an explicit null. Transport options use None to inherit their defaults. Timeout means a number of seconds or httpx.Timeout. Supply parameters marked Required to Python or to the API, even when the generated signature permits omission.

JSON response objects expose data, quotas, metadata and http_response. Check optional fields for None. See First call for the response envelope. CSV methods return text and iterators yield items.

HTTP failures raise an APIError subclass based on the response: BadRequestError, AuthenticationError, InsufficientCreditsError, PermissionDeniedError, NotFoundError, ConflictError, GoneError, UnprocessableEntityError, RateLimitError, DailyLimitError, KeyCreditLimitError, UnavailableForLegalReasonsError or InternalServerError. See the error mapping and retry rules.

enrich_persons

Send 1 to 25,000 items. Nested item dictionaries use the API names, such as linkedinUrl, firstName and externalId.

def enrich_persons(
    *,
    items: list[models.BulkEnrichPersonsParamsItemsItem | dict[str, object]] | NotGiven | None = NOT_GIVEN,
    families: list[str] | NotGiven | None = NOT_GIVEN,
    email_type: str | NotGiven | None = NOT_GIVEN,
    live: bool | NotGiven | None = NOT_GIVEN,
    name: str | NotGiven | None = NOT_GIVEN,
    webhook_url: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    idempotency_key: str | None = None,
    **extra: object,
) -> Result[models.BulkEnrichPersonsData]: ...

Parameters

Returns

Result[models.BulkEnrichPersonsData]. data.job.id identifies the Bulk job. The acknowledgement also contains duplicate_count, credits_estimated and not_run_for_credits. Follow the job with client.bulk.wait(job_id). See Lists and Bulk enrichment.

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid SDK options. Malformed typed response data can raise Pydantic ValidationError.

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.bulk.enrich_persons(
        items=[{"linkedinUrl": "https://social.com/in/janedoe", "externalId": "crm-001"}],
        families=["profile"],
        name="CRM enrichment",
    )
    print(result.data if result is not None else None)

list

Call Job history with client.bulk.list().

def list(
    *,
    type: str | NotGiven | None = NOT_GIVEN,
    status: str | NotGiven | None = NOT_GIVEN,
    list_id: str | NotGiven | None = NOT_GIVEN,
    per_page: int | NotGiven | None = NOT_GIVEN,
    cursor: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Page[models.ListJobsItem]: ...

Parameters

Returns

Page[models.ListJobsItem]. A page with records in data, a next_cursor, has_next_page() and get_next_page(). The next-page method reuses the filters and returns None after the last page.

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid SDK options. Malformed typed response data can raise Pydantic ValidationError.

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    page = client.bulk.list(per_page=20)
    for item in page.data:
        if item is not None:
            print(item.to_dict())

list_all

Read every job-history page with client.bulk.list_all(per_page=100). In SDK 0.3.0, omitting per_page starts the iterator at a page size of 200, reduced by any remaining max_results cap. The API accepts at most 100 per page, so set per_page explicitly to a value from 1 to 100.

def list_all(
    *,
    type: str | NotGiven | None = NOT_GIVEN,
    status: str | NotGiven | None = NOT_GIVEN,
    list_id: str | NotGiven | None = NOT_GIVEN,
    per_page: int | NotGiven | None = NOT_GIVEN,
    cursor: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    max_results: int | None = None,
    **extra: object,
) -> Iterator[models.ListJobsItem | None]: ...

Parameters

Returns

Iterator[models.ListJobsItem | None]. An iterator of typed records. Entries can be None. The iterator fetches pages only as you advance. Pagination is free. Omit max_results to read all pages.

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid SDK options, invalid max_results or per_page, or a repeated pagination cursor. Malformed typed response data can raise Pydantic ValidationError.

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    for item in client.bulk.list_all(per_page=100, max_results=20):
        if item is not None:
            print(item.to_dict())

retrieve

Call Get a job with client.bulk.retrieve().

def retrieve(
    job_id: str,
    *,
    wait: int | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.GetJobData]: ...

Parameters

Returns

Result[models.GetJobData]. data contains one job state, including status, progress, credits, error and links.

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid SDK options or a wait outside the integer range 0 to 20. Malformed typed response data can raise Pydantic ValidationError.

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.bulk.retrieve("00000000-0000-4000-8000-000000000001", wait=20)
    print(result.data if result is not None else None)

results

Results are available once the job is completed or cancelled, as CSV (the default) or with format="ndjson" as one JobResultLine JSON object per line.

def results(
    job_id: str,
    *,
    format: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> str: ...

Parameters

Returns

str. The completed or cancelled job's results as text, one row per item in input order: the CSV, or NDJSON with format="ndjson".

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid SDK options. ConflictError with JOB_RESULTS_NOT_READY means the file is not ready. ConflictError with JOB_RESULTS_FORMAT_UNAVAILABLE means the job was stored before NDJSON existed: download its CSV.

Example

import json

from reversecontact import ReverseContact

with ReverseContact() as client:
    job_id = "00000000-0000-4000-8000-000000000001"
    csv_text = client.bulk.results(job_id)
    ndjson = client.bulk.results(job_id, format="ndjson")
    items = [json.loads(line) for line in ndjson.splitlines() if line]
    print(len(csv_text), len(items))

rows

Read one page of results, in the order sent, from the start of the run. While the job runs, a page stops at the first item not finished: data is empty and next_cursor is set while the next item runs, so read it again after Retry-After. next_cursor is None once nothing more will come. Available from SDK 0.3.0.

def rows(
    job_id: str,
    *,
    cursor: str | NotGiven | None = NOT_GIVEN,
    limit: int | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Page[models.JobResultLine]: ...

Parameters

Returns

Page[models.JobResultLine], with the items in data, next_cursor, has_next_page() and get_next_page(). extras["status"] is the job status when the page was read. A page can hold fewer items than limit.

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid SDK options. ConflictError with JOB_RESULTS_FORMAT_UNAVAILABLE means the job was stored before reading by page existed: download its CSV with results(). RateLimitError with JOB_ROWS_BUSY means too many pages are being read at once: the SDK retries it as the retry rules describe.

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    page = client.bulk.rows("00000000-0000-4000-8000-000000000001", limit=100)
    for item in page.data:
        print(item.row, item.status)
    print(page.extras["status"], page.next_cursor)

iter_rows

Read the results one item at a time, in the order sent, as they become ready, whatever the job is doing. While the next item runs, the iterator waits Retry-After (2 seconds by default) and reads the same cursor again. It ends when next_cursor is None, or when the job is paused, since nothing moves until someone resumes it: read on later with rows() and the last cursor. A cancelled job still finishes the items it had started, within the hour, and the iterator waits for them too. Available from SDK 0.3.0. The async client has the same method, used with async for.

def iter_rows(
    job_id: str,
    *,
    cursor: str | None = None,
    limit: int | None = None,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
) -> Iterator[models.JobResultLine | None]: ...

Parameters

Returns

An iterator of models.JobResultLine items, in the order sent.

Errors

The errors of rows().

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    for item in client.bulk.iter_rows("00000000-0000-4000-8000-000000000001"):
        print(item.row, item.input.get("externalId"), item.status, item.credits_consumed)

cancel

Call Cancel a job with client.bulk.cancel().

def cancel(
    job_id: str,
    *,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.CancelJobData]: ...

Parameters

Returns

Result[models.CancelJobData]. data contains the job state after cancellation, including status, progress and credits.

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid SDK options. Malformed typed response data can raise Pydantic ValidationError.

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.bulk.cancel("00000000-0000-4000-8000-000000000001")
    print(result.data if result is not None else None)

wait

Call Get a job with client.bulk.wait().

def wait(
    job_id: str,
    *,
    timeout: float = 1800,
    poll_wait: int = 20,
    on_poll: Callable[[Result[GetJobData]], None] | None = None,
    headers: Mapping[str, str] | None = None,
) -> Result[GetJobData]: ...

Parameters

Returns

Result[GetJobData]. data contains the job when the status leaves queued or running, including completed, cancelled, failed or paused. Inspect status. Failed and paused jobs are returned without JobFailedError.

Errors

APIError subclasses follow the HTTP mapping above. APIConnectionError reports transport failures. APITimeoutError reports timed-out attempts. ReverseContactError covers invalid poll_wait or timeout. JobTimeoutError reports an expired deadline. Failed or paused server states are returned for inspection. Malformed typed response data can raise Pydantic ValidationError.

Example

from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.bulk.wait("00000000-0000-4000-8000-000000000001")
    print(result.data if result is not None else None)

Related guides

See the Python SDK overview, Lists and bulk and Lists.