API documentation

One endpoint verifies both email and phone. Authenticate with a Bearer token, send a value, and get back a normalized result with a 0–100 confidence score. Email verifications cost 1 credit, phone (HLR) 8 — the exact amount is returned in the response's cost field.

Get an API key Interactive API reference ↗

Authentication

Pass your key in the Authorization header. Keys look like cf_live_… or cf_test_…. Create and revoke them on the Keys page.

Verify an email

POST /v1/verify (unified) or POST /v1/verify/email.

curl -X POST https://checkfor.dev/v1/verify \
  -H "Authorization: Bearer cf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "type": "email", "value": "ada@lovelace.io" }'

Verify a phone number

POST /v1/verify/phone. The optional country hint helps parse national-format numbers.

curl -X POST https://checkfor.dev/v1/verify/phone \
  -H "Authorization: Bearer cf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155552671", "country": "US" }'

Example response

{
  "type": "email",
  "input": "ada@lovelace.io",
  "valid": true,
  "score": 92,
  "cost": 1,
  "details": {
    "valid": true,
    "deliverable": true,
    "disposable": false,
    "role": false,
    "catchAll": false,
    "mxFound": true,
    "smtp": "ok",
    "reason": null
  },
  "requestId": "req_a1b2c3",
  "creditsRemaining": 4991
}

TypeScript SDK

The typed @checkfor/sdk client wraps the same endpoints and returns the shared NormalizedResult envelope.

import { CheckforClient } from '@checkfor/sdk';

const client = new CheckforClient({
  apiKey: process.env.CHECKFOR_API_KEY!,
  baseUrl: 'https://checkfor.dev',
});

const email = await client.verifyEmail('ada@lovelace.io');
const phone = await client.verifyPhone('+14155552671', 'US');

console.log(email.valid, email.score, phone.details.lineType);

Status codes

200	Success — normalized result. Email costs 1 credit, phone 8.
400	Bad input — the value or type failed validation.
401	Missing or invalid API key.
402	Not enough credits — upgrade your plan on the Billing page.
429	Rate limited — see the Retry-After header.
502 / 503	Upstream provider failure — never billed. Retry shortly.
500	Internal error — never billed.