client.fetch

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

Create client by following Install and configure. 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.

person()

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

client.fetch.person(
  params: Body<"fetchPerson">,
  options?: RequestOptions
): Promise<Result<Data<"fetchPerson">> | null>

Parameters

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

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.

client.fetch.personLive(
  params: Body<"livePerson">,
  options?: RequestOptions
): Promise<Job<Person>>

Parameters

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

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.

client.fetch.checkPerson(
  params: Body<"checkPerson">,
  options?: RequestOptions
): Promise<Result<Data<"checkPerson">>>

Parameters

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

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.

client.fetch.company(
  params: Body<"fetchCompany">,
  options?: RequestOptions
): Promise<Result<Data<"fetchCompany">> | null>

Parameters

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

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.

client.fetch.companyLive(
  params: Body<"liveCompany">,
  options?: RequestOptions
): Promise<Job<Company>>

Parameters

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

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.

client.fetch.checkCompany(
  params: Body<"checkCompany">,
  options?: RequestOptions
): Promise<Result<Data<"checkCompany">>>

Parameters

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

const result = await client.fetch.checkCompany({ url: "https://social.com/company/acme" });
console.log(result.data);

Related guides

First call, Async jobs. Return to the TypeScript SDK overview.