POST /verify

Verify the license status of a healthcare provider across multiple government data sources in a single API call.

Endpoint

POST https://api.veriflowapi.com/v1/verify

Request headers

Header	Required	Value
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes	`application/json`

Request body

{
  "first_name": "Sarah",
  "last_name": "Chen",
  "state": "FL",
  "npi": "1234567890",
  "dob": "1975-03-15"
}

Request parameters

Parameter	Type	Required	Description
`first_name`	string	Yes	Provider’s first name. Fuzzy matching handles minor typos and variations.
`last_name`	string	Yes	Provider’s last name.
`state`	string	Yes	Two-letter US state code (e.g. `CA`, `TX`, `NY`). The state where the license was issued.
`npi`	string	No	10-digit National Provider Identifier. Strongly recommended — significantly improves match accuracy.
`dob`	string	No	Date of birth in ISO 8601 format (`YYYY-MM-DD`). Disambiguates same-name providers and, in particular, clears false OIG exclusion matches on common names. See OIG exclusion matching.

Note on npi and dob: Both are optional but strongly recommended whenever available. Without them, identity resolution relies on name and state alone, which can produce false positives for common names — including false matches against the OIG exclusion list. Supplying npi and/or dob disambiguates the provider and clears same-name collisions.

Response

Success response — 200 OK

{
  "verified": true,
  "status": "active",
  "match_confidence": "high",
  "name": "Dr. Sarah Chen",
  "license_number": "ME149820",
  "state": "Florida",
  "expiry_date": "2027-06-30",
  "disciplinary_flags": false,
  "oig_excluded": false,
  "sources_checked": [
    "NPPES",
    "OIG",
    "FL Department of Health"
  ],
  "source_live": true,
  "cached": false,
  "cache_expires_at": "2026-02-21T10:30:00Z",
  "checked_at": "2026-02-20T10:30:00Z",
  "verification_id": "vrf_a1b2c3d4e5",
  "certificate_hash": "sha256_9f8e7d6c5b4a3b2c1d..."
}

Response fields

Field	Type	Description
`verified`	boolean	Top-level pass/fail. `true` if provider was found, license is active, and no OIG exclusion exists.
`status`	string	Current license status. See Status Values below.
`match_confidence`	string	Strength of the identity match: `high` (matched by NPI), `medium` (exact name), `low` (name nickname/typo variant), or `null` when not found. Lower values are name-only matches — supply an `npi` for `high`. See Identity resolution.
`name`	string	Provider’s full name as it appears in source records.
`license_number`	string	State license number.
`state`	string	Full state name.
`expiry_date`	string	License expiry date in ISO 8601 format (`YYYY-MM-DD`).
`disciplinary_flags`	boolean	`true` if any disciplinary actions, sanctions, or malpractice findings are on record.
`oig_excluded`	boolean	`true` if the provider matches the HHS OIG exclusion list. A matching `npi` or `dob` confirms; a different `npi` or `dob` rules out a same-name stranger; a name-only match is reported conservatively (still `true`). See OIG exclusion matching.
`sources_checked`	array	List of data sources checked in this request.
`source_live`	boolean	`true` if data was fetched live from source. `false` if served from cache.
`cached`	boolean	Whether this response was served from cache.
`cache_expires_at`	string	ISO 8601 timestamp when this cached result will be refreshed.
`checked_at`	string	ISO 8601 timestamp of when this verification was performed.
`verification_id`	string	Unique identifier for this verification. Use for audit trail and certificate retrieval.
`certificate_hash`	string	SHA256 hash of the signed verification certificate.

Status values

Status	Description	`verified` value
`active`	License is current and in good standing	`true`
`inactive`	License exists but is not currently active	`false`
`suspended`	License has been temporarily suspended	`false`
`expired`	License has passed its expiry date	`false`
`revoked`	License has been permanently revoked	`false`
`not_found`	No matching provider found in sources checked	`false`

Identity resolution

Before verifying license status, VeriflowAPI resolves provider identity by matching the last name exactly, then the first name. First-name matching accepts:

Nicknames where one form is a prefix of the other (e.g. “Bob” vs “Robert”)
Middle initials included or omitted
Hyphenated last names
Minor typos in submitted names

It deliberately does not match genuinely different given names that merely look alike (e.g. “John” vs “Joan”, “Satish” vs “Satinder”). Those return not_found rather than a false match — a wrong-person confirmation is worse than a miss. Every successful match reports a match_confidence:

Confidence	Meaning
`high`	Matched on the `npi` — exact identity.
`medium`	Exact first + last name, no NPI.
`low`	Name nickname/typo variant, no NPI.

Because name-only matching is inherently ambiguous for common names, supply an npi whenever available for high-confidence, exact-identity verification. When ambiguity cannot be resolved, we return not_found.

OIG exclusion matching

The OIG LEIE (List of Excluded Individuals/Entities) is matched by name and then narrowed by the identifiers you supply. Because roughly 90% of LEIE records carry no NPI, name is the primary key — so a common name can collide with an excluded stranger. VeriflowAPI uses npi and dob to resolve those collisions:

A matching npi confirms the exclusion — the strongest signal, an exact identity match.
A different npi or dob on a same-name record rules it out as a different person, so oig_excluded returns false.
A name-only match — no identifier supplied, or none on the LEIE record — is reported conservatively as oig_excluded: true. We would rather surface a possible match for your review than silently clear a real exclusion.

To avoid false positives on common names, supply dob (and npi where you have it) on every check. Most LEIE records carry a date of birth, so a dob clears a same-name stranger even when the record has no NPI.

Sandbox & testing

Test keys (vf_test_) run against the same data and coverage as production — an ordinary provider returns exactly what a live key would, including unsupported_state for states we don’t yet cover. This makes your sandbox integration faithful to production. To exercise every branch of your integration deterministically, use reserved test last names (case-insensitive) on a vf_test_ key. They work in any state and force a specific outcome, similar to test card numbers:

Last name	Result
`Sandbox_Active`	`verified: true`, `status: "active"`
`Sandbox_Expired`	`status: "expired"`, not verified
`Sandbox_Suspended`	`status: "suspended"`, not verified, disciplinary flag
`Sandbox_Revoked`	`status: "revoked"`, not verified, disciplinary flag
`Sandbox_NotFound`	`status: "not_found"`, not verified (also simulates a name mismatch)
`Sandbox_Excluded`	`oig_excluded: true`, not verified
`Sandbox_Disciplined`	`verified: true`, `disciplinary_flags: true`

To simulate unsupported_state, query any state we don’t cover (e.g. OH) with an ordinary name. These triggers apply only to test keys — on a live key they are treated as ordinary names.

Caching policy

To maximize uptime and minimize response time, VeriflowAPI caches responses according to the following TTL policy:

Data type	Cache TTL
State license status (active/inactive/suspended/expired/revoked)	24 hours
NPPES identity (name, NPI)	24 hours
OIG exclusion status	12 hours

When a response is served from cache, cached will be true and source_live will be false. The cache_expires_at field tells you exactly when fresh data will be fetched. This caching policy means VeriflowAPI maintains 99.9% uptime even when government source sites experience downtime.

Error responses

400 Bad Request

Returned when required parameters are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: last_name",
    "docs": "https://docs.veriflowapi.com/api-reference/verify"
  }
}

401 Unauthorized

Returned when the API key is missing or invalid.

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or missing API key.",
    "docs": "https://docs.veriflowapi.com/authentication"
  }
}

429 Too Many Requests

Returned when you exceed your plan’s rate limit.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your monthly verification quota. Upgrade your plan or contact support.",
    "reset_at": "2026-03-01T00:00:00Z",
    "docs": "https://docs.veriflowapi.com/rate-limits"
  }
}

503 Service Unavailable

Returned in the rare case that all data sources are unavailable and no cached data exists.

{
  "error": {
    "code": "sources_unavailable",
    "message": "All data sources are temporarily unavailable. We are working to restore service. Check status.veriflowapi.com for updates.",
    "docs": "https://docs.veriflowapi.com/api-reference/verify"
  }
}

Code examples

Python

import requests

def verify_provider(api_key, first_name, last_name, state, npi=None, dob=None):
    payload = {
        "first_name": first_name,
        "last_name": last_name,
        "state": state
    }
    if npi:
        payload["npi"] = npi
    if dob:
        payload["dob"] = dob

    response = requests.post(
        "https://api.veriflowapi.com/v1/verify",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        },
        json=payload
    )

    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"API error {response.status_code}: {response.json()}")

Node.js

const axios = require('axios');

async function verifyProvider(apiKey, { firstName, lastName, state, npi, dob }) {
  const response = await axios.post(
    'https://api.veriflowapi.com/v1/verify',
    {
      first_name: firstName,
      last_name: lastName,
      state,
      ...(npi && { npi }),
      ...(dob && { dob })
    },
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data;
}

Ruby

require 'net/http'
require 'json'
require 'uri'

def verify_provider(api_key, first_name:, last_name:, state:, npi: nil, dob: nil)
  uri = URI('https://api.veriflowapi.com/v1/verify')
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = "Bearer #{api_key}"
  request['Content-Type'] = 'application/json'
  request.body = {
    first_name: first_name,
    last_name: last_name,
    state: state,
    npi: npi,
    dob: dob
  }.compact.to_json

  response = http.request(request)
  JSON.parse(response.body)
end

Getting Started

API Reference

Features

Compliance & Security

Support

POST /verify

POST /verify

Endpoint

Request headers

Request body

Request parameters

Response

Success response — 200 OK

Response fields

Status values

Identity resolution

OIG exclusion matching

Sandbox & testing

Caching policy

Error responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

503 Service Unavailable

Code examples

Python

Node.js

Ruby

​POST /verify

​Endpoint

​Request headers

​Request body

​Request parameters

​Response

​Success response — 200 OK

​Response fields

​Status values

​Identity resolution

​OIG exclusion matching

​Sandbox & testing

​Caching policy

​Error responses

​400 Bad Request

​401 Unauthorized

​429 Too Many Requests

​503 Service Unavailable

​Code examples

​Python

​Node.js

​Ruby

POST /verify

Endpoint

Request headers

Request body

Request parameters

Response

Success response — 200 OK

Response fields

Status values

Identity resolution

OIG exclusion matching

Sandbox & testing

Caching policy

Error responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

503 Service Unavailable

Code examples

Python

Node.js

Ruby