client.contact

Start jobs to find email addresses or phone numbers, or verify an email address.

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.

Contact methods generate an Idempotency-Key for each call and reuse that key on automatic retries. Save an explicit idempotencyKey to retry after restarting. See Safe retries.

findEmail()

Provide url or id. You can also use fullName with companyDomain, or firstName and lastName with companyDomain. If you supply both URL and id, id takes precedence. emailType defaults to professional.

client.contact.findEmail(
  params: Body<"findContactEmail">,
  options?: IdempotentRequestOptions
): Promise<Job<ContactValue[]>>

Parameters

Returns

A Job<ContactValue[]>, with the webhookId in job.id. Call await job.wait() to get data.result, an array of { value, type } email entries. 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. If you supply an invalid idempotency key, the SDK raises ReverseContactError before sending a request.

Example

const job = await client.contact.findEmail({ fullName: "Jane Doe", companyDomain: "acme.com" });
console.log("Save job id:", job.id);
const done = await job.wait();
for (const email of done.data.result ?? []) console.log(email.value, email.type);

verifyEmail()

Provide the email address to verify. Addresses returned by Find Email are already verified.

client.contact.verifyEmail(
  params: Body<"verifyContactEmail">,
  options?: IdempotentRequestOptions
): Promise<Job<EmailVerification>>

Parameters

Returns

A Job<EmailVerification>, with the webhookId in job.id. Call await job.wait() to get data.result with email and status. The status is valid, risky, invalid or unknown. 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. If you supply an invalid idempotency key, the SDK raises ReverseContactError before sending a request.

Example

const job = await client.contact.verifyEmail({ email: "jane@acme.com" });
console.log("Save job id:", job.id);
const done = await job.wait();
console.log(done.data.result?.status);

findPhone()

Provide url or id. You can also use fullName with companyDomain, or firstName and lastName with companyDomain. If you supply both URL and id, id takes precedence.

client.contact.findPhone(
  params: Body<"findContactPhone">,
  options?: IdempotentRequestOptions
): Promise<Job<ContactValue[]>>

Parameters

Returns

A Job<ContactValue[]>, with the webhookId in job.id. Call await job.wait() to get data.result, an array of { value, type } phone entries. 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. If you supply an invalid idempotency key, the SDK raises ReverseContactError before sending a request.

Example

const job = await client.contact.findPhone({ url: "https://social.com/in/janedoe" });
console.log("Save job id:", job.id);
const done = await job.wait();
for (const phone of done.data.result ?? []) console.log(phone.value, phone.type);

Related guides

Async jobs, Errors and retries. Return to the TypeScript SDK overview.