RealPhoneValidation plugin

• A refusal can arrive inside a 200. These services predate HTTP error conventions: an unrecognised token answers {"status":"unauthorized"}, a missing one {"status":"ERROR","error_text":"missing token"}, and a bad number {"status":"invalid phone"}, all with a 200. The plugin checks the body and throws, so a caller never mistakes a refusal for a disposition. In front of the scripts, the load balancer answers a token it does not recognise with an empty 401 and a malformed one with an empty 403, the same status as the documented throttle for more than 10 calls a second; a 5xx means the service is down.
• ? is not “no”. On dncLookup and dncPlus, national_dnc, state_dnc, dma and litigator answer Y, N or ?, where ? means the list timed out or could not be checked. Treat ? as unknown; reading it as cleared is exactly the mistake that creates a TCPA problem.
• reassigned: "no_data" is not "no". no_data means the carriers recorded no change since 27 January 2021, which is not evidence about a particular number. Only yes and no answer the question you asked.
• active and connected are different questions. active says the number sits on a provider still in business; it deliberately does not say anyone answers. Use turboV3, turboStandard, turbo or scrub for connectivity and active only for existence.
• Five services overlap. turboV3 gives the most (connection, phone type, caller name, carrier, caller type); turboStandard gives connection and phone type; the legacy turbo gives connection, iscell and carrier; scrub and scrubPlus are the cheap list-processing options and may answer unknown for up to 5% of US numbers. Pick one per workflow rather than chaining them.
• error_text is {} when there is nothing to report. It is an empty object rather than an empty string or absent, and the same holds for RESPONSEMSG on the RESPONSECODE routes. The response models accept either shape. Other text fields come from the same XML conversion, so an empty one (a caller_name the carrier does not expose, say) is returned as null.
• fraudCheck returns numeric strings. score is a string from 0 to 1000 and phn_type is a code explained by phn_desc. They are not parsed here, so a caller comparing them should convert them and see a non-numeric value rather than have it silently coerced.
• reassigned needs your consent date. contact_date is the date you received permission to contact, in YYYY-MM-DD; a reassignment only means anything relative to that date.
• dncLookup needs a SAN number from the national registry before the service will answer.
• Rate limit. The docs recommend 10 calls a second and refuse a burst with a 403 and an empty body. The plugin retries that three times with exponential backoff, waiting for a Retry-After header if one arrives. A malformed token gets the same 403, so a typo in the token shows up as a throttle after those retries.

• 12 typed API operations

​

Setup

npm install corsair @corsair-dev/realphonevalidation better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/realphonevalidation better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/realphonevalidation better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/realphonevalidation better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { realphonevalidation } from '@corsair-dev/realphonevalidation';

export const corsair = createCorsair({
	plugins: [
		realphonevalidation(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

realphonevalidation()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'realphonevalidation',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.realphonevalidation.api.turboV3({ phone: '7275555555' });

​

What’s next