Integration Guide

1 Prerequisites

• A Validator account — sign up here (no subscription required).
• An API key from your tenant portal.
• Prepaid wallet balance for the operations you plan to run. See pricing.

2 Authentication

Pass your API key in the Authorization header as a Bearer token. There are no cookies, no sessions, and no OAuth flows for API calls.

Authorization: Bearer vlt_your_api_key_here

API keys begin with vlt_. Keep them secret — treat them like passwords.

3 Phone check

POST /v1/check/phone runs the base phone check — line type, carrier, city, state, county, ZIP, rate centre, LATA, timezone and OCN — for US and Canadian numbers. Enable any of the phone components with a boolean key to go deeper — the components you tick are the request.

Request

{
  "phone": "+18134696697",
  "dncCheck": true
}

Response (200)

{
  "ok": true,
  "phone": {
    "status": "valid",
    "confidence": 0.98,
    "e164": "+18134696697",
    "lineType": "mobile",
    "carrierName": "T-Mobile USA",
    "reference": {
      "lineType": "mobile",
      "carrierName": "T-Mobile USA",
      "ocn": "6529",
      "state": "FL",
      "city": "Tampa",
      "county": "Hillsborough",
      "zip": "33601",
      "rateCenter": "TAMPA",
      "lata": "952",
      "timezone": "America/New_York",
      "companyType": "wireless",
      "smsGateway": false
    },
    "dnc": {
      "callable": true,
      "onFederalDnc": false,
      "onStateDnc": false,
      "onLitigator": false,
      "onComplainer": false,
      "resolvedState": "FL",
      "stateDncApplicable": true,
      "recommendation": "call"
    },
    "checked": ["base", "dncCheck"],
    "source": "vendor"
  },
  "billing": {
    "charged": true,
    "operations": ["check_phone", "check_phone_dnc"],
    "totalMicroUsd": 40500,
    "totalCredits": 81
  }
}

Every endpoint returns this one envelope: ok, a phone and/or email half, and billing. Fields that were not checked are omitted — never false or null. The totals above are illustrative; read GET /v1/pricing for live prices. totalMicroUsd is the exact amount charged (1,000,000 micro = $1.00); totalCredits is the same amount in credits (1 credit = $0.0005).

4 Email check

POST /v1/check/email runs the base email check — syntax, domain, MX, disposable addresses, role addresses and blocklist signals. Enable emailVerify for mailbox-level verification or emailPremium for verification plus catch-all and abuse scoring. Both replace the base check rather than adding to it.

Request

{
  "email": "[email protected]",
  "emailVerify": true
}

Response (200)

{
  "ok": true,
  "email": {
    "status": "valid",
    "confidence": 0.97,
    "reason": "mailbox_verified",
    "hasMx": true,
    "disposable": false,
    "roleBased": false,
    "dnsblHit": false,
    "mailboxVerified": true,
    "checked": ["base", "emailVerify"],
    "source": "vendor"
  },
  "billing": {
    "charged": true,
    "operations": ["check_email_verify"],
    "totalMicroUsd": 10000,
    "totalCredits": 20
  }
}

Note the single operation in billing.operations: emailVerify replaced the base check, so the base is not billed alongside it.

5 Both in one call

POST /v1/check accepts a phone, an email, or both, with any mix of phone and email components in one body. Each half is validated against its own family, runs concurrently, and is billed on its own outcome. Only the halves you supplied an identifier for appear in the response. Enabling a component for a family whose identifier is missing is a 400 — the request asked for a check that could not run.

Request

{
  "phone": "+18134696697",
  "email": "[email protected]",
  "carrierCheck": true,
  "emailPremium": true
}

Response (200)

{
  "ok": true,
  "phone": {
    "status": "valid",
    "confidence": 0.99,
    "e164": "+18134696697",
    "lineType": "mobile",
    "carrierName": "T-Mobile",
    "reference": { "…": "…" },
    "portability": {
      "ported": true,
      "portedDate": "2024-04-05",
      "carrierChanged": true,
      "carrierNative": "AERIAL COMMUNICATIONS, INC.",
      "carrierServing": "T-MOBILE USA, INC.",
      "provenance": "npac"
    },
    "checked": ["base", "carrierCheck"],
    "source": "vendor"
  },
  "email": {
    "status": "valid",
    "confidence": 0.97,
    "reason": "mailbox_verified",
    "hasMx": true,
    "disposable": false,
    "roleBased": false,
    "dnsblHit": false,
    "mailboxVerified": true,
    "catchAll": false,
    "abuseScore": 0,
    "checked": ["base", "emailPremium"],
    "source": "vendor"
  },
  "billing": {
    "charged": true,
    "operations": ["check_phone_carrier", "check_email_premium"],
    "totalMicroUsd": 79500,
    "totalCredits": 159
  }
}

When a component has no answer

HTTP stays 200 and ok stays true. The component is listed in unavailable with a reason, its fields are absent, and it is not billed. A replacement tier that cannot complete returns the base result and charges the base only — partial bundle output is never emitted.

{
  "ok": true,
  "phone": {
    "status": "valid",
    "confidence": 0.95,
    "e164": "+18134696697",
    "lineType": "mobile",
    "reference": { "…": "…" },
    "checked": ["base"],
    "unavailable": [{ "option": "activeCheck", "reason": "vendor_unavailable" }],
    "source": "internal"
  },
  "billing": {
    "charged": true,
    "operations": ["check_phone"],
    "totalMicroUsd": 1000,
    "totalCredits": 2
  }
}

6 Components

Each component is a boolean key on the request. A component adds when it is a separate lookup on top of the base check, and replaces the base when its own operation already does the base's work — so you are never charged for the same reference lookup twice. A component another selected component already includes is one check, billed once: carrierCheck covers portedCheck, phonePremium covers every phone upgrade, and emailPremium covers emailVerify.

Prices per component are on the pricing page and in GET /v1/pricing. The price calculator (or the API call builder in your portal once you are signed in) shows the exact request and response for any selection.

7 Error codes

All error responses are { "ok": false, "error": "…" } with a human-readable description, plus the fields named above where they apply. A conclusive "status": "invalid" is a successful check (HTTP 200, ok: true), not an error.

8 Billing

Integration test mode

POST /v1/check/phone
Authorization: Bearer <api_key>
{
  "phone": "+18134696697",
  "test": true
}

Verification sessions