client.search

Search people and companies, count matches, and set a limit on the paid results you retrieve.

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.

Page methods return a Page with the items in data and the next page identified by nextCursor. Use hasNextPage() to check the cursor. Call getNextPage() to request that page, or get null when there is no next page. Prompt pages also expose interpretation. See Search within a budget.

people()

Provide at least one search filter. Pagination alone is not a filter.

client.search.people(
  params: Omit<Body<"searchPeople">, "perPage"> & { perPage?: number },
  options?: RequestOptions
): Promise<Page<Data<"searchPeople">["data"][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.search.people({ firstName: "Jane", perPage: 10 });
for (const person of page.data) console.log(person.firstName);

peopleByPrompt()

client.search.peopleByPrompt(
  params: Omit<Body<"searchPeopleByPrompt">, "perPage"> & { perPage?: number },
  options?: RequestOptions
): Promise<Page<Data<"searchPeopleByPrompt">["data"][number], Data<"searchPeopleByPrompt">["interpretation"]>>

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. interpretation contains the filters extracted from the prompt.

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.search.peopleByPrompt({ prompt: "Software founders in Paris", perPage: 10 });
console.log(page.interpretation, page.data);

peopleLookalike()

Provide exactly one seed, url or id. The API rejects additional search filters. The seed must already be in the search index.

client.search.peopleLookalike(
  params: Omit<Body<"searchPeopleLookalike">, "perPage"> & { perPage?: number },
  options?: RequestOptions
): Promise<Page<Data<"searchPeopleLookalike">["data"][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. A seed absent from the search index raises NotFoundError, rather than returning null.

Example

const page = await client.search.peopleLookalike({ url: "https://social.com/in/janedoe", perPage: 10 });
console.log(page.data);

countPeople()

Provide at least one search filter. Count before requesting paid profiles.

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

Parameters

Returns

A response envelope with the free match count in data.count.

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.search.countPeople({ firstName: "Jane" });
console.log("Matches:", result.data.count);

peopleAutoSuggestion()

client.search.peopleAutoSuggestion(
  params: Body<"searchPeopleAutoSuggestion">,
  options?: RequestOptions
): Promise<Result<Data<"searchPeopleAutoSuggestion">>>

Parameters

Returns

A response with suggested skill values in data. The response contains no profiles.

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.search.peopleAutoSuggestion({ field: "skills", query: "machine l", limit: 10 });
console.log(result.data);

organizations()

Provide at least one search filter. Pagination alone is not a filter.

client.search.organizations(
  params: Omit<Body<"searchOrganizations">, "perPage"> & { perPage?: number },
  options?: RequestOptions
): Promise<Page<Data<"searchOrganizations">["data"][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.search.organizations({ companyName: "Acme", perPage: 10 });
console.log(page.data);

organizationsByPrompt()

client.search.organizationsByPrompt(
  params: Omit<Body<"searchOrganizationsByPrompt">, "perPage"> & { perPage?: number },
  options?: RequestOptions
): Promise<Page<Data<"searchOrganizationsByPrompt">["data"][number], Data<"searchOrganizationsByPrompt">["interpretation"]>>

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. interpretation contains the filters extracted from the prompt.

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.search.organizationsByPrompt({ prompt: "Software companies in France", perPage: 10 });
console.log(page.interpretation, page.data);

countOrganizations()

Provide at least one search filter. Counting companies is free.

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

Parameters

Returns

A response envelope with the free match count in data.count.

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.search.countOrganizations({ companyName: "Acme" });
console.log("Matches:", result.data.count);

peopleFields()

client.search.peopleFields(
  options?: RequestOptions
): Promise<Result<Data<"searchPeopleAvailableFields">>>

Parameters

Returns

A response envelope with the available people search filters 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.search.peopleFields();
console.log(result.data);

organizationsFields()

client.search.organizationsFields(
  options?: RequestOptions
): Promise<Result<Data<"searchOrganizationsAvailableFields">>>

Parameters

Returns

A response envelope with the available company search filters 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.search.organizationsFields();
console.log(result.data);

iterPeople()

Use the same input as people(). Set maxResults to cap the results. With maxResults: 0, the iterator sends no request.

client.search.iterPeople(
  params: Omit<Body<"searchPeople">, "perPage"> & { perPage?: number },
  options: SearchIteratorOptions
): AsyncGenerator<Data<"searchPeople">["data"][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 result of client.search.iterPeople(
  { firstName: "Jane" },
  { maxResults: 20 }
)) {
  console.log(result);
}

iterPeopleByPrompt()

Use the same input as peopleByPrompt(). Set maxResults to cap the results. Prompt searches also charge per page. With maxResults: 0, the iterator sends no request.

client.search.iterPeopleByPrompt(
  params: Omit<Body<"searchPeopleByPrompt">, "perPage"> & { perPage?: number },
  options: SearchIteratorOptions
): AsyncGenerator<Data<"searchPeopleByPrompt">["data"][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 result of client.search.iterPeopleByPrompt(
  { prompt: "Software founders in Paris" },
  { maxResults: 20 }
)) {
  console.log(result);
}

iterPeopleLookalike()

Use the same input as peopleLookalike(). Set maxResults to cap the results. With maxResults: 0, the iterator sends no request.

client.search.iterPeopleLookalike(
  params: Omit<Body<"searchPeopleLookalike">, "perPage"> & { perPage?: number },
  options: SearchIteratorOptions
): AsyncGenerator<Data<"searchPeopleLookalike">["data"][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. A seed absent from the search index raises NotFoundError, rather than returning null.

Example

for await (const result of client.search.iterPeopleLookalike(
  { url: "https://social.com/in/janedoe" },
  { maxResults: 20 }
)) {
  console.log(result);
}

iterOrganizations()

Use the same input as organizations(). Set maxResults to cap the results. With maxResults: 0, the iterator sends no request.

client.search.iterOrganizations(
  params: Omit<Body<"searchOrganizations">, "perPage"> & { perPage?: number },
  options: SearchIteratorOptions
): AsyncGenerator<Data<"searchOrganizations">["data"][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 result of client.search.iterOrganizations(
  { companyName: "Acme" },
  { maxResults: 20 }
)) {
  console.log(result);
}

iterOrganizationsByPrompt()

Use the same input as organizationsByPrompt(). Set maxResults to cap the results. Prompt searches also charge per page. With maxResults: 0, the iterator sends no request.

client.search.iterOrganizationsByPrompt(
  params: Omit<Body<"searchOrganizationsByPrompt">, "perPage"> & { perPage?: number },
  options: SearchIteratorOptions
): AsyncGenerator<Data<"searchOrganizationsByPrompt">["data"][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 result of client.search.iterOrganizationsByPrompt(
  { prompt: "Software companies in France" },
  { maxResults: 20 }
)) {
  console.log(result);
}

Related guides

Search within a budget, Filter values as constants. Return to the TypeScript SDK overview.