API Documentation

Zero dependencies, uses the platform fetch — so it runs on Node 18+, Bun, Deno, Cloudflare Workers and the browser alike.

npm install veriastra

import { Veriastra, VeriastraError } from "veriastra";

const veriastra = new Veriastra(process.env.VERIASTRA_API_KEY);

const result = await veriastra.dialCheck("+14155552671");
console.log(result.decision);   // "clear" | "caution" | "do-not-call"

try {
  await veriastra.hlr("+14155552671");
} catch (e) {
  if (e instanceof VeriastraError && e.isOutOfCredits) await topUp();
}

Every POST carries an Idempotency-Key, and a retry reuses the same one — so a retried call replays the first answer instead of being charged twice. Errors arrive as typed objects: branch on code, never on the message.

No key? Every single-lookup method also answers on the rate-limited keyless tier, so you can try the engines before you sign up.

The whole API is described in OpenAPI 3.1 at /api/openapi.json. Point Swagger UI or Scalar at it, or generate a typed client in your language of choice.

For Postman there is a ready-made collection at /api/postman — every endpoint, auth already wired to an apiKey variable, and each request body pre-filled with a working example. Import the link, paste a key, press Send. It is generated from the spec above on every request, so it cannot fall out of step with the API.

# generate a client (any openapi-generator target)
npx @openapitools/openapi-generator-cli generate \
  -i https://veriastra.com/api/openapi.json \
  -g typescript-fetch -o ./veriastra-client

Each operation carries an x-credits extension with its cost, so you can budget a workload straight from the spec.

A request that times out at the network layer leaves you unable to tell whether we processed it. Send an Idempotency-Key header and retrying is safe: the first response is stored for 24 hours and replayed verbatim, without charging a second credit.

curl -X POST https://veriastra.com/api/v1/verify-email \
  -H "Authorization: Bearer ol_live_…" \
  -H "Idempotency-Key: order-4417-attempt" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

# a replayed response carries:  Idempotent-Replay: true

Use any string you can regenerate for the same logical operation, up to 255 characters: an order id, a job id, a UUID you keep with the record. Keys are scoped to your API key and to the endpoint, so the same string on two endpoints is two separate operations. Only successful responses are stored; a 4xx or 5xx stays retryable, because the condition behind it may have changed.

Bulk jobs POST their result to the webhook URL you supply. Every delivery is signed, so you can prove it came from us before you act on it:

X-Veriastra-Signature: t=1785580802,v1=6f1c…

// signed value is  `${t}.${rawBody}`  — verify in Node:
const crypto = require("node:crypto");
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const age = Math.abs(Math.floor(Date.now()/1000) - Number(parts.t));
  if (age > 300) return false;                       // replay window
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Your signing secret is unique to each API key. Read it from GET /api/account (field webhookSecret). Verify against the raw request body, before parsing it: re-serialised JSON will not match. The timestamp is inside the signed value, so it cannot be edited to replay an old body under a new time.

Without a key you get 5 requests per minute and 50 per day, per IP. That tier exists so the free tools work and you can try an endpoint, not as a production API. With a key there is no per-minute ceiling: your limit is the credit balance, and X-Credits-Remaining tells you where you stand after every call.

Hitting the guest limit returns 429 with Retry-After in seconds. An exhausted balance returns 402.

After the first few guest calls of a day, the API answers 428 with a proof-of-work challenge: find a solution such that SHA-256 of challenge:solution starts with difficulty zero bits, then retry with X-Veriastra-Proof: challenge:solution. It costs a browser about a tenth of a second and each challenge is single-use. This keeps the free tools usable by people rather than by proxy pools — requests with an API key are never challenged.

Results are cached per data type (email ~1 day, IP ~7 days, domain ~3 days, phone ~30 days) and a cache hit is marked with "cached": true. It still costs a credit, because the answer is the product. When you need to see a change that just happened, add "bypass_cache": true and the engine re-runs; the fresh answer replaces the cached one.

GET /api/bulk/{jobId} returns status and results as JSON. For a large job, two other shapes avoid buffering the whole thing:

# one JSON object per line, streamed — process record 1 while 9,000 is still arriving
curl -H "Authorization: Bearer $KEY" \
  "https://veriastra.com/api/v1/bulk/$JOB?format=ndjson" | while read -r line; do
    echo "$line" | jq -r '.input'
  done

# a spreadsheet, or a file for the compliance folder
curl -H "Authorization: Bearer $KEY" \
  "https://veriastra.com/api/v1/bulk/$JOB?format=csv" -o results.csv

Both are streamed with the same ownership check as the JSON form: a job created with a key is readable only by that key.

Branch on code, never on the message: the code is a stable contract, the message is human text we may reword. Every error body also carries retryable and a recovery sentence, so a client does not have to infer intent from a status code.