Versium REACH API Software Development Kit (SDK) for Node.js

A simplified TypeScript-based interface for accessing Versium Reach APIs via Node.js

Note

This SDK does not yet support the Versium Bulk APIs. If you are interested in using the SDK for operating the Bulk APIs, please reach out to api-support@versium.com

Installation

npm install @versium/reach-api-sdk-node

Supports Node.js v16+.

Note

This package is an ESM-only module - you are not able to import it with require(). See the Node.js documentation for more information on using ES modules.

Usage

1. Import the ReachClient class:

import ReachClient from "@versium/reach-api-sdk-node";

2. Create a new client instance:

const client = new ReachClient("your-api-key");

Appending Data

For adding data to a set of inputs, use the append method. Check the API documentation for which data tools and output types are available.

Important

This method returns an AsyncGenerator that yields arrays containing API responses, you must iterate over the generator to get the response arrays, then iterate over the response arrays to get the results.

const inputs = [
  {
    first: "john",
    last: "doe",
    address: "123 Trinity St",
    city: "Redmond",
    state: "WA",
    zip: "98052",
  },
];

// iterate over the AsyncGenerator to get the response arrays, note the 'for await' syntax here
for await (const results of client.append("contact", inputs, {
  outputTypes: ["email", "phone"],
  additionalParams: {
    // any request-level params supported by Versium APIs
    cfg_max_emails: 3,
  },
})) {
  // filter out failed queries for processing later
  const failedResults = results.filter((result) => !result.success);

  // iterate over the response array to get the results
  results.forEach((result, idx) => {
    if (result.success && result.matchFound) {
      // merge successful matches with inputs
      inputs[idx].appendResults = result.body.versium.results;
    }
  });
}

Legacy (deprecated): pass an array of output types

Prior to v1.1.0 the third argument was an array of output types. This form still works for backward compatibility but is deprecated—please migrate to the options object shown above.

for await (const results of client.append("contact", inputs, [
  "email",
  "phone",
])) {
  // ...
}

Note

You can also include parameters inside individual input records when you need per-record settings, e.g. const inputs = [{ first: "john", last: "doe", cfg_max_emails: 1 }, { first: "jane", last: "doe", cfg_max_emails: 5 }]. If a parameter exists both in an input record and in additionalParams, the value from the input record takes precedence.

List Generation

For retrieving a list of records, use the listgen method. This function returns a promise that resolves to a response object with a getRecords function on it which returns an AsyncGenerator for iterating over records from the response stream. The listgen method will return as soon as data begins streaming in, and getRecords can be used to drain the stream until you have extracted all records from the response. Check the API documentation for which data tools and output types are available.

const response = await client.listgen("abm", { domain: ["versium.com"] }, [
  "abm_email",
  "abm_online_audience",
]);

if (response.success) {
  // getRecords returns an AsyncGenerator, so here we use the 'for await' syntax to iterate over the results
  for await (const record of response.getRecords()) {
    console.log({ record });
  }
}

Things to keep in mind

• The default rate limit is 20 queries per second
• You must have a provisioned API key for this function to work. If you are unsure where to find your API key, look at our API key documentation

Contributing

For information on building and testing the library, see CONTRIBUTING.md