> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/sdk/javascript/fetch
> 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.fetch

> Use client.fetch in the Reverse Contact TypeScript SDK to read cached profiles, check freshness or start live jobs, with parameters, costs and examples.

- Last verified: 2026-11-04

Read cached profiles, check availability, or start a live profile job.

| Method | Endpoint | Cost |
| ------ | -------- | ---- |
| `client.fetch.person()` | [Person profile](https://docs.reversecontact.com/endpoints/fetch-profile) | 1 credit when the profile is found in the cache. A 404 is free. |
| `client.fetch.personLive()` | [Person profile live](https://docs.reversecontact.com/endpoints/fetch-profile-live) | 2 credits per request, consumed when the job is created. |
| `client.fetch.checkPerson()` | [Person profile status](https://docs.reversecontact.com/endpoints/check-person) | Free. Requires at least 2 workspace credits. A lower balance returns 402 NO_CREDITS. |
| `client.fetch.company()` | [Company profile](https://docs.reversecontact.com/endpoints/fetch-company) | 1 credit when the company is found in the cache. A 404 is free. |
| `client.fetch.companyLive()` | [Company profile live](https://docs.reversecontact.com/endpoints/fetch-company-live) | 2 credits per request, consumed when the job is created. |
| `client.fetch.checkCompany()` | [Company profile status](https://docs.reversecontact.com/endpoints/check-company) | Free. Requires at least 2 workspace credits. A lower balance returns 402 NO_CREDITS. |

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

## person()

Provide `url` or `id`. If you supply both, `id` takes precedence.

**Signature**

```typescript [TypeScript SDK]
client.fetch.person(
  params: Body<"fetchPerson">,
  options?: RequestOptions
): Promise<Result<Data<"fetchPerson">> | null>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` **required** | `Body<"fetchPerson">` | Request body. See the fields and their requirements below. |
| `params.url` **conditional** | `string` | Public Social profile URL (e.g. `https://social.com/in/janedoe`). Required unless `id` is given. |
| `params.id` **conditional** | `string` | Reverse Contact person id from a previous response (e.g. `prs_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given. |
| `options` | `RequestOptions` | Optional per-request `timeout`, `maxRetries`, `headers` and `signal`. See [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). |

**Returns**

`Result<Data<"fetchPerson">>` with the cached person directly in `data`, or `null` when no profile matches.

**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. A lookup with no match returns `null`. An unknown route still raises `NotFoundError`.

**Example**

**Example**

```typescript [TypeScript SDK]
const result = await client.fetch.person({ url: "https://social.com/in/janedoe" });
console.log(result?.data ?? "No cached profile");
```

## personLive()

Provide exactly one of `url` or `id`. Omit `webhookUrl` to poll, or supply an HTTPS callback URL.

**Signature**

```typescript [TypeScript SDK]
client.fetch.personLive(
  params: Body<"livePerson">,
  options?: RequestOptions
): Promise<Job<Person>>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` **required** | `Body<"livePerson">` | Request body. See the fields and their requirements below. |
| `params.url` **conditional** | `string` | Public Social profile URL (e.g. `https://social.com/in/janedoe`). Provide exactly one of `url` or `id`. |
| `params.id` **conditional** | `string` | Reverse Contact person id (`prs_…`). The gateway resolves it to the current Social public slug before starting the scrape. |
| `params.webhookUrl` | `string` | HTTPS push URL for webhook delivery. Omit this field to retrieve the result via [polling](https://docs.reversecontact.com/guides/polling) (recommended). See the [Webhooks guide](https://docs.reversecontact.com/guides/webhooks) when you need push delivery. |
| `options` | `RequestOptions` | Optional per-request `timeout`, `maxRetries`, `headers` and `signal`. See [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). |

**Returns**

A `Job<Person>`, with the `webhookId` in `job.id`. Call `await job.wait()` to get the profile in `data.result`. Waiting is free. See [Async jobs](https://docs.reversecontact.com/sdk/javascript/async-jobs) for `wait()` options and webhook delivery.

**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 job = await client.fetch.personLive({ url: "https://social.com/in/janedoe" });
console.log("Save job id:", job.id);
const done = await job.wait();
console.log(done.data.result?.firstName);
```

## checkPerson()

Provide `url` or `id`. If you supply both, `id` takes precedence. The check is free but requires at least 2 workspace credits.

**Signature**

```typescript [TypeScript SDK]
client.fetch.checkPerson(
  params: Body<"checkPerson">,
  options?: RequestOptions
): Promise<Result<Data<"checkPerson">>>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` **required** | `Body<"checkPerson">` | Request body. See the fields and their requirements below. |
| `params.url` **conditional** | `string` | Public Social profile URL (e.g. `https://social.com/in/janedoe`). Required unless `id` is given. |
| `params.id` **conditional** | `string` | Reverse Contact person id from a previous response (e.g. `prs_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given. |
| `options` | `RequestOptions` | Optional per-request `timeout`, `maxRetries`, `headers` and `signal`. See [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). |

**Returns**

A response with profile availability and freshness in `data`. The check does not fetch a full profile.

**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 result = await client.fetch.checkPerson({ url: "https://social.com/in/janedoe" });
console.log(result.data);
```

## company()

Provide `url` or `id`. If you supply both, `id` takes precedence.

**Signature**

```typescript [TypeScript SDK]
client.fetch.company(
  params: Body<"fetchCompany">,
  options?: RequestOptions
): Promise<Result<Data<"fetchCompany">> | null>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` **required** | `Body<"fetchCompany">` | Request body. See the fields and their requirements below. |
| `params.url` **conditional** | `string` | Public Social company URL (e.g. `https://social.com/company/acme-corp`). Required unless `id` is given. |
| `params.id` **conditional** | `string` | Reverse Contact company id from a previous response (e.g. `com_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given. |
| `options` | `RequestOptions` | Optional per-request `timeout`, `maxRetries`, `headers` and `signal`. See [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). |

**Returns**

`Result<Data<"fetchCompany">>` with the cached company directly in `data`, or `null` when no company matches.

**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. A lookup with no match returns `null`. An unknown route still raises `NotFoundError`.

**Example**

**Example**

```typescript [TypeScript SDK]
const result = await client.fetch.company({ url: "https://social.com/company/acme" });
console.log(result?.data ?? "No cached company");
```

## companyLive()

Provide exactly one of `url` or `id`. Omit `webhookUrl` to poll, or supply an HTTPS callback URL.

**Signature**

```typescript [TypeScript SDK]
client.fetch.companyLive(
  params: Body<"liveCompany">,
  options?: RequestOptions
): Promise<Job<Company>>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` **required** | `Body<"liveCompany">` | Request body. See the fields and their requirements below. |
| `params.url` **conditional** | `string` | Public Social company URL (e.g. `https://social.com/company/acme-corp`). Provide exactly one of `url` or `id`. |
| `params.id` **conditional** | `string` | Reverse Contact company id (`com_…`). The gateway resolves it to the current Social public slug before starting the scrape. |
| `params.webhookUrl` | `string` | HTTPS push URL for webhook delivery. Omit this field to retrieve the result via [polling](https://docs.reversecontact.com/guides/polling) (recommended). See the [Webhooks guide](https://docs.reversecontact.com/guides/webhooks) when you need push delivery. |
| `options` | `RequestOptions` | Optional per-request `timeout`, `maxRetries`, `headers` and `signal`. See [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). |

**Returns**

A `Job<Company>`, with the `webhookId` in `job.id`. Call `await job.wait()` to get the company in `data.result`. Waiting is free. See [Async jobs](https://docs.reversecontact.com/sdk/javascript/async-jobs) for `wait()` options and webhook delivery.

**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 job = await client.fetch.companyLive({ url: "https://social.com/company/acme" });
console.log("Save job id:", job.id);
const done = await job.wait();
console.log(done.data.result);
```

## checkCompany()

Provide `url` or `id`. If you supply both, `id` takes precedence. The check is free but requires at least 2 workspace credits.

**Signature**

```typescript [TypeScript SDK]
client.fetch.checkCompany(
  params: Body<"checkCompany">,
  options?: RequestOptions
): Promise<Result<Data<"checkCompany">>>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `params` **required** | `Body<"checkCompany">` | Request body. See the fields and their requirements below. |
| `params.url` **conditional** | `string` | Public Social company URL (e.g. `https://social.com/company/acme-corp`). Required unless `id` is given. |
| `params.id` **conditional** | `string` | Reverse Contact company id from a previous response (e.g. `com_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given. |
| `options` | `RequestOptions` | Optional per-request `timeout`, `maxRetries`, `headers` and `signal`. See [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). |

**Returns**

A response with company availability and freshness in `data`. The check does not fetch a full profile.

**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 result = await client.fetch.checkCompany({ url: "https://social.com/company/acme" });
console.log(result.data);
```

## Related guides

[First call](https://docs.reversecontact.com/sdk/javascript/first-call), [Async jobs](https://docs.reversecontact.com/sdk/javascript/async-jobs). Return to the [TypeScript SDK overview](https://docs.reversecontact.com/sdk/javascript).

## FAQ

### Which SDK method reads a cached person profile?

`client.fetch.person()` returns the cached person directly in `result.data`, or `null` when no cached profile matches.

### How do I get a live profile with the TypeScript SDK?

Call `client.fetch.personLive()` or `client.fetch.companyLive()`, save `job.id`, and call `job.wait()` for the final result.

### Are profile availability checks free?

`client.fetch.checkPerson()` and `client.fetch.checkCompany()` are free, but the workspace must have at least 2 credits.