API reference

Authentication

Create a key in Dashboard → API keys. Send it as a bearer token (or an x-api-key header). Keys belong to a workspace and spend its credits.

One account can manage multiple workspaces, each with its own credits, members and validation records. Create multiple named API keys within each workspace for different apps or environments. Workspace owners and admins can revoke keys individually; revoking one does not replace the others. A key can access only its own workspace, not every workspace in your account.

Authorization: Bearer bc_live_xxxxxxxxxxxxxxxx

Verify email

Costs 1 credit.

curl -X POST https://your-domain/api/public/v1/email/verify \
  -H "Authorization: Bearer $BYTECHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.com"}'

{
  "id": "6f1c…",
  "object": "email_validation",
  "email": "jane@acme.com",
  "status": "valid",            // see Statuses
  "score": 94,                  // 0–100 confidence
  "reason": "Mailbox exists and accepts mail",
  "domain": "acme.com",
  "suggestion": null,           // e.g. "jane@gmail.com" for "jane@gmial.com"
  "checks": {
    "syntax": true, "mx": true, "smtp": true, "catch_all": false,
    "disposable": false, "role_based": false, "free_provider": false
  },
  "engine": "bytemine",
  "credits_remaining": 24999
}

Find email

Finds a work email from a person's name and company domain. Costs 5 credits only when an email is found (status: "found"); not_found and catch_all results are free. Personal and disposable domains are not supported.

curl -X POST https://your-domain/api/public/v1/email/find \
  -H "Authorization: Bearer $BYTECHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jane","last_name":"Doe","domain":"acme.com"}'

{
  "id": "2a7d…",
  "object": "email_find",
  "first_name": "Jane",
  "last_name": "Doe",
  "domain": "acme.com",
  "email": "jane.doe@acme.com",   // null when not found
  "status": "found",              // found | catch_all | not_found
  "score": 70,
  "confidence": "medium",         // high | medium | low | null
  "catch_all": null,
  "reason": "Most common company pattern (preview — mailbox not confirmed)",
  "credits_charged": 5,
  "engine": "preview",
  "credits_remaining": 95
}

For bulk finding, send "type":"finder" to /v1/bulk with items like {"first_name":"Jane","last_name":"Doe","domain":"acme.com"}. 5 credits per person are held up front and returned for anyone not found.

Bulk jobs

Up to 50,000 items. Duplicates are removed before charging. Credits are reserved up front. Optionally pass a webhook_url to be notified on completion.

curl -X POST https://your-domain/api/public/v1/bulk \
  -H "Authorization: Bearer $BYTECHECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"email","name":"March leads","items":["a@x.com","b@y.com"]}'

// 202 Accepted
{ "id": "9b2e…", "object": "bulk_job", "status": "processing", "total": 2, "processed": 2, ... }

Poll for progress. Add ?include=results&page=0 to page through results (1,000 per page).

Lists your 50 most recent jobs.

Account

Email pricing fields shown below; additional response fields are omitted.

{ "object": "account", "workspace": "Acme", "credits": 24997, "pricing": { "email": 1 } }

Statuses

• valid — Safe to send.
• invalid — Does not exist or is malformed.
• risky — Exists but may hurt deliverability (e.g. role-based).
• catch_all — Domain accepts all mail; mailbox can't be confirmed.
• disposable — Temporary mailbox provider.
• unknown — Couldn't be determined right now.

Limits

Limits depend on the largest credit pack your workspace has bought. Going over a limit returns 429 (or 413 for an oversized bulk job) and costs no credits.

Errors

{ "error": { "code": "insufficient_credits", "message": "Not enough credits. Top up in Billing." } }

• 400 invalid_request
• 401 unauthorized
• 402 insufficient_credits
• 404 not_found
• 413 too_many_rows
• 429 rate_limited · concurrency_limited · too_many_jobs
• 500 internal_error

Webhooks

Configure endpoints in Dashboard → Webhooks. Events: bulk.completed, credits.low. Each request carries x-bytecheck-event and x-bytecheck-signature: sha256=<hex> — an HMAC-SHA256 of the raw body using your endpoint secret.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}