> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/sdk/javascript/jobs
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# client.jobs

> Use client.jobs in the Reverse Contact TypeScript SDK to read or resume asynchronous live-fetch and contact jobs, handle failures and set wait deadlines.

- Last verified: 2026-11-04

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

| Method | Endpoint | Cost |
| ------ | -------- | ---- |
| `client.jobs.retrieve()` | [Polling](https://docs.reversecontact.com/guides/polling) | Free and does not count toward rate limits. |
| `client.jobs.wait()` | [Polling](https://docs.reversecontact.com/guides/polling) | Free and does not count toward rate limits. |

Create `client` by following [Install and configure](https://docs.reversecontact.com/sdk/javascript/install). 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](https://docs.reversecontact.com/sdk/javascript/first-call) for response handling.

HTTP errors use the [APIError subclasses and retry rules](https://docs.reversecontact.com/sdk/javascript/errors-and-retries): `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](https://docs.reversecontact.com/sdk/javascript/bulk). The `Job` returned by a live fetch or contact lookup also has `job.retrieve()` and `job.wait()` methods. See [Async jobs](https://docs.reversecontact.com/sdk/javascript/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.

**Signature**

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

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `id` **required** | `string` | Saved `job.id` / `webhookId` from a live fetch or contact lookup. |
| `params` | `{     wait?: number;   }` | Query parameters. Omit to use the defaults. |
| `params.wait` | `number` | Hold a long poll for 0 to 20 seconds. Defaults to 0. |
| `options` | `RequestOptions` | Optional per-request `timeout`, `maxRetries`, `headers` and `signal`. See [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). |

**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**

**Example**

```typescript [TypeScript SDK]
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.

**Signature**

```typescript [TypeScript SDK]
client.jobs.wait<T = unknown>(
  id: string,
  options?: WaitOptions<JobSnapshot<T>>
): Promise<Result<JobSnapshot<T>>>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `id` **required** | `string` | Saved `job.id` / `webhookId` from a live fetch or contact lookup. |
| `options` | `WaitOptions<JobSnapshot<T>>` | Optional overall `timeout`, `pollWait`, `onPoll`, `headers` and `signal`. See [Wait options](https://docs.reversecontact.com/sdk/javascript/timeouts). |

**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**

**Example**

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

## Related guides

[Async jobs](https://docs.reversecontact.com/sdk/javascript/async-jobs), [client.bulk](https://docs.reversecontact.com/sdk/javascript/bulk), [Timeouts and cancellation](https://docs.reversecontact.com/sdk/javascript/timeouts). Return to the [TypeScript SDK overview](https://docs.reversecontact.com/sdk/javascript).

## FAQ

### Which job ids does client.jobs accept?

`client.jobs` accepts webhook job ids from live fetches and contact lookups. Use `client.bulk` for background Bulk job ids.

### Does client.jobs.wait start another paid lookup?

`client.jobs.wait()` polls an existing job for free. Waiting does not submit a replacement lookup.

### How does client.jobs report a failed job?

`client.jobs.retrieve()` returns the errored snapshot for inspection. `client.jobs.wait()` raises `JobFailedError` when the job status is `errored`.