client.jobs

Read or wait for the webhook jobs started by live fetches and contact lookups.

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.

client.jobs reads /v2/webhooks/:webhookId. Background jobs under /v2/jobs/:jobId use client.bulk. The Job returned by a live fetch or contact lookup also has job.retrieve() and job.wait() methods. See Async jobs.

retrieve()

Read the current state of a webhook job. Use the webhookId from a live fetch or contact lookup, not a background Bulk job id.

client.jobs.retrieve<T = unknown>(
  id: string,
  params?: {
    wait?: number;
  },
  options?: RequestOptions
): Promise<Result<JobSnapshot<T>>>

Parameters

Returns

Result<JobSnapshot<T>> with data.status, data.result and data.creditsConsumed. You can inspect the snapshot even when the job has failed. Use wait() to raise an error on job failure.

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 snapshot = await client.jobs.retrieve(jobId, { wait: 20 });
console.log(snapshot.data.status, snapshot.data.result);

wait()

Resume waiting for a saved live-fetch or contact job without submitting another paid lookup. The generic T describes the result type. The SDK does not validate the profile shape.

client.jobs.wait<T = unknown>(
  id: string,
  options?: WaitOptions<JobSnapshot<T>>
): Promise<Result<JobSnapshot<T>>>

Parameters

Returns

Result<JobSnapshot<T>> once data.status is succeeded. A failed job raises JobFailedError instead.

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. Waiting raises JobFailedError for an errored job and JobTimeoutError when the overall deadline expires.

Example

const done = await client.jobs.wait(jobId, { timeout: 30 * 60 * 1000 });
console.log(done.data.result, done.data.creditsConsumed);

Related guides

Async jobs, client.bulk, Timeouts and cancellation. Return to the TypeScript SDK overview.