TypeScript and JavaScript SDK

Introduction

@reverse-contact/sdk is the official TypeScript and JavaScript client for the Reverse Contact API. It covers every endpoint with typed requests and results. The client handles safe retries, waits for asynchronous tasks, and pages through search results within a budget you set. It has no runtime dependencies.

• Package: @reverse-contact/sdk on npm
• Source code and issues: github.com/visum-run/reversecontact-node
• License: Apache-2.0

The SDK runs on Node.js 22 and later, Bun, Deno, and edge runtimes that provide the standard Fetch API, AbortController and crypto.randomUUID. It ships as ESM and CommonJS.

These guides describe the published SDK version 0.4.1. The Python SDK is also available for Python 3.11 and later. Keep API keys on your server: browser construction is rejected by default.

Install

npm install @reverse-contact/sdk

First call

Set RC_API_KEY on your server, then run this example. A successful person enrichment costs 2 credits. A lookup with no match is free.

import ReverseContact from "@reverse-contact/sdk";

const client = new ReverseContact();
const result = await client.enrich.person({ email: "jane.doe@acme.com" });
console.log(result?.data.person ?? "No confident match");

Endpoints and methods

Look for the TypeScript SDK tab in endpoint code examples. For now, the List and Bulk examples are in Lists and Bulk. Request fields use the API's camelCase names.

Where to go next

• Install and configure
• First call
• client.enrich
• client.fetch
• client.search
• client.contact
• client.lists
• client.bulk
• client.tasks
• client.usage
• Async tasks
• Lists and Bulk
• Search within a budget
• Filter values as constants
• Errors and retries
• Timeouts and cancellation
• Client options
• Without the SDK

API key

Keep the key on your server and pass apiKey, or let the client read RC_API_KEY. See Install and configure.

Lookups that find nothing

Check for null when a lookup finds no profile. See First call for response handling.

Async tasks: live fetch, Find Email and Find Phone

Use task.wait() to poll for free, for up to 30 minutes by default. A failed task raises TaskFailedError. Save task.id to resume with client.tasks.wait() after a restart. See Async tasks.

Webhook delivery instead of polling

Receive results at an HTTPS webhook and parse deliveries in Async tasks.

Lists and Bulk

Use Lists and Bulk to create Lists, track imports, and read Bulk results as they come or download them.

Search within a budget

Count for free, then use the required maxResults iterator option to cap requested results. See Search within a budget.

Filter values as constants

Use Filter values as constants to autocomplete supported values in your editor.

Errors and retries

The SDK retries per-minute limits and HTTP 500, 502, 503 and 504 up to 4 times. Daily limits, key credit limits and missing credits are not retried. Read Errors and retries.

Safe retries on Find Email and Find Phone

Contact lookups reuse an idempotency key across retries, including HTTP 409 IDEMPOTENCY_KEY_IN_USE. Outside per-minute rate limits, other 4xx errors are not retried. Read Errors and retries.

Timeouts and cancellation

See Timeouts and cancellation to set a timeout for each HTTP attempt or cancel local requests.

Client options

Set transport, logging, headers and per-request overrides with Client options.

Without the SDK

To call the API with an HTTP client or generate one from OpenAPI, see Without the SDK.