@verixo/sdk

Official Node.js SDK for the VerifiedCore API.

Install

npm install @verixo/sdk

Verify: send one-time codes to your own users

Send a code to your user's phone at sign-up, login or 2FA, then check what they typed. VerifiedCore generates, delivers, rate-limits and expires the code.

import Verixo, { VerixoError } from "@verixo/sdk";

const vc = new Verixo(process.env.VC_API_KEY);

// 1. Send a code
const v = await vc.verify.start({ to: "+2348031234567", ip: req.ip });

// 2. Check the code your user typed
const r = await vc.verify.check({ id: v.id, code: userInput });
if (r.valid) {
  // signed in
} else {
  console.log(`${r.attemptsRemaining} attempts left`);
}

With a vc_test_ key nothing is sent or charged, and the code is always 123456, so you can build your flow end-to-end before going live.

Other calls: vc.verify.get(id), vc.verify.list({ page, size }), vc.verify.settings() and vc.verify.updateSettings({ brandName, allowedCountries, codeLength, ttlSeconds }).

Failures throw a VerixoError whose code says why, e.g. COUNTRY_NOT_ALLOWED, INVALID_NUMBER, RESEND_TOO_SOON or RATE_LIMITED.

Numbers

import Verixo from "@verixo/sdk";

const vc = new Verixo(process.env.VC_API_KEY);

const { numbers } = await vc.numbers.search({
  serviceSlug: "whatsapp",
  countryCode: "NG",
  minScore: 80,
  limit: 5,
});

const session = await vc.numbers.purchase({
  serviceSlug: "whatsapp",
  countryCode: "NG",
});

vc.subscribe(session.sessionToken, ({ otp, latencyMs }) => {
  console.log(`OTP: ${otp} in ${latencyMs}ms`);
});

Note: purchase() takes serviceSlug + countryCode, not a specific numberId -- the server picks the best available number by Health Score at purchase time, since a candidate returned by search() may already be gone by the time you'd reference it back.

Polling instead of WebSocket push

subscribe() requires a persistent connection, which isn't always practical (e.g. serverless functions). Use sessions.waitForOtp() instead:

const result = await vc.sessions.waitForOtp(session.sessionToken);
if (result.status === "DELIVERED") console.log(result.otpCode);

Errors

All non-2xx responses throw a VerixoError with status, and usually code/detail from the API's error body:

import { VerixoError } from "@verixo/sdk";

try {
  await vc.numbers.purchase({ serviceSlug: "whatsapp", countryCode: "NG" });
} catch (err) {
  if (err instanceof VerixoError && err.status === 402) {
    console.log("Insufficient wallet balance");
  }
}

Requirements

Node.js 18+ for fetch. subscribe() additionally requires a global WebSocket implementation, built into Node 22+ and all browsers; on Node 18-21, polyfill globalThis.WebSocket (e.g. with the ws package) before calling subscribe().

Development

npm install
npm run build       # tsup -> dist/ (ESM + CJS + .d.ts)
npm run typecheck
node examples/quickstart.mjs   # requires VC_API_KEY env var, see file header