client.bulk

Submit people for Bulk enrichment, then check progress, wait for the job to stop, cancel the job, read its results as they come or download them.

Create client by following Install and configure. The examples use a saved jobId from the relevant job family. The @reverse-contact/sdk package exports Body, Data, Query and the other types used in the signatures.

JSON responses contain data and optional quotas and metadata. They also include the original response, with its body already read. See First call for response handling.

HTTP errors use the APIError subclasses and retry rules: BadRequestError, AuthenticationError, InsufficientCreditsError, PermissionDeniedError, NotFoundError, ConflictError, GoneError, UnprocessableEntityError, RateLimitError, DailyLimitError, KeyCreditLimitError, UnavailableForLegalReasonsError and InternalServerError, according to the API response. Other statuses use APIError.

enrichPersons()

Send 1 to 25,000 items. The SDK generates an Idempotency-Key if you omit it and reuses the key on automatic retries. Save your own key to repeat the same submission after a restart.

client.bulk.enrichPersons(
  params: Body<"bulkEnrichPersons">,
  options?: IdempotentRequestOptions
): Promise<Result<Data<"bulkEnrichPersons">>>

Parameters

Returns

A response envelope with the background job in data.job. Save data.job.id, then call client.bulk.wait(id). See Lists and Bulk enrichment. This is not a Job object.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const created = await client.bulk.enrichPersons({
  items: [{ linkedinUrl: "https://social.com/in/janedoe", externalId: "crm-001" }],
  families: ["profile"]
}, { idempotencyKey: "crm-export-2026-11-04" });
console.log("Save job id:", created.data.job.id);
const progress = await client.bulk.wait(created.data.job.id);
console.log(progress.data.status);

list()

Read background job history, including Bulk enrichment and List jobs allowed by the API key permissions.

client.bulk.list(
  params?: Query<"listJobs">,
  options?: RequestOptions
): Promise<Page<Data<"listJobs">["items"][number], undefined>>

Parameters

Returns

A Page with results in data and pagination through nextCursor, hasNextPage() and getNextPage(). The page also includes optional quotas and metadata, and the original response.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const page = await client.bulk.list({ type: "enrich_persons", perPage: 20 });
console.log(page.data);

retrieve()

Read the current state of a background job. Use wait to hold the request while the job is queued or running.

client.bulk.retrieve(
  jobId: string,
  params?: Query<"getJob">,
  options?: RequestOptions
): Promise<Result<Data<"getJob">>>

Parameters

Returns

Result<BulkJob> with the current status, progress, credit usage and result links in data.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const result = await client.bulk.retrieve(jobId, { wait: 20 });
console.log(result.data.status, result.data.credits);

results()

Download only when links.results is set, after the job completes or is cancelled. Failed jobs have no results file.

client.bulk.results(
  jobId: string,
  params?: Query<"getJobResults">,
  options?: RequestOptions
): Promise<string>

Parameters

Returns

A string: the CSV without its byte order mark, or with format: "ndjson" one JSON object per line. Prepend "\uFEFF" when saving the CSV for spreadsheet applications.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports 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

const job = await client.bulk.retrieve(jobId);
if (job.data.links.results) {
  const csv = await client.bulk.results(jobId);
  const ndjson = await client.bulk.results(jobId, { format: "ndjson" });
  const items = ndjson.split("\n").filter(Boolean).map((line) => JSON.parse(line));
  console.log(csv.length, items.length);
}

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 nextCursor is set while the next item runs, so read it again after Retry-After. nextCursor is null once nothing more will come. Available from SDK 0.3.0.

client.bulk.rows(
  jobId: string,
  params?: Query<"getJobRows">,
  options?: RequestOptions
): Promise<Page<PageItem<Data<"getJobRows">>, Interpretation<Data<"getJobRows">>>>

Parameters

Returns

A Page with JobResultLine items in data, nextCursor and getNextPage(), like list(). extras.status is the job status when the page was read. A page can hold fewer items than limit. The page also includes optional quotas and metadata, and the original response.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response. 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 after Retry-After, as Errors and retries describes.

Example

const page = await client.bulk.rows(jobId, { limit: 100 });
for (const item of page.data) console.log(item.row, item.status);
console.log(page.extras.status, page.nextCursor);

iterateRows()

Read the results one item at a time, 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 position again. It ends with the job, 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.

client.bulk.iterateRows(
  jobId: string,
  params?: Query<"getJobRows">,
  options?: RequestOptions
): AsyncGenerator<JobResultLine, void, unknown>

Parameters

Returns

An AsyncGenerator of JobResultLine items, in the order sent. The @reverse-contact/sdk package exports the JobResultLine type.

Errors

The errors of rows(). Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError.

Example

for await (const item of client.bulk.iterateRows(jobId)) {
  console.log(item.row, item.input.externalId, item.status, item.creditsConsumed);
}

cancel()

Request a server-side stop. Items that have not started are not charged.

client.bulk.cancel(
  jobId: string,
  options?: RequestOptions
): Promise<Result<Data<"cancelJob">>>

Parameters

Returns

A response envelope with the cancellation acknowledgement in data.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response.

Example

const result = await client.bulk.cancel(jobId);
console.log(result.data);

wait()

Wait while the background job is queued or running. A paused job returns control to your code even though the job can resume later.

client.bulk.wait(
  jobId: string,
  options?: WaitOptions<BulkJob>
): Promise<Result<BulkJob>>

Parameters

Returns

Result<BulkJob> when the status is completed, cancelled, failed or paused. A failed status does not raise JobFailedError. Check data.status.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response. JobTimeoutError means the overall wait deadline has expired. An unsuccessful terminal state does not raise JobFailedError.

Example

const result = await client.bulk.wait(jobId, { timeout: 30 * 60 * 1000 });
console.log(result.data.status, result.data.links.results);

listAll()

client.bulk.listAll(
  params?: Query<"listJobs">,
  options?: ListIteratorOptions
): AsyncGenerator<Data<"listJobs">["items"][number], void, unknown>

Parameters

Returns

An AsyncGenerator of individual results. The iterator requests pages as needed. A repeated cursor raises ReverseContactError.

Errors

Calls can raise the HTTP APIError subclasses listed above. Network failures or cancellation raise APIConnectionError, and attempt timeouts raise APITimeoutError. ReverseContactError reports invalid SDK options or an invalid successful JSON response. ReverseContactError also reports invalid perPage or maxResults values and repeated cursors.

Example

for await (const job of client.bulk.listAll({ type: "enrich_persons" })) {
  console.log(job.id, job.status);
}

Related guides

Lists and Bulk enrichment, Timeouts and cancellation. Return to the TypeScript SDK overview.