FAQ
Contractor verification API and MCP server: common questions.
Short answers about what Better Vetters checks, which places are covered, how billing works, and how to use it from an AI agent. Each answer links to the page with the details.
FAQ
General
What is Better Vetters?
Better Vetters is a pay-per-call API and MCP server that tells an AI agent whether a US contractor is real, licensed, and pulling permits. It checks official state license boards and city permit portals and returns a verdict, a 0 to 100 trust score, and the public records behind them. It is operated by James Russell, a sole proprietor based in Waterford, PA.
How do I get an API key?
Send POST https://api.bettervetters.com/v1/keys with a JSON body such as {"label":"my-agent"}. The key includes 20 free checks, needs no card, and is shown once. Key creation is limited to 5 per IP address per day.
What is the API base URL and where is the spec?
The base URL is https://api.bettervetters.com. The OpenAPI 3.1 spec is at https://api.bettervetters.com/openapi.json and an interactive reference is at https://api.bettervetters.com/docs.
What does Better Vetters check?
One call returns whether a US contractor matches a license record, the license’s status and expiry, insurance and bond on file (WA and OR), permit activity in the covered city (WA, TX, NYC, and Pittsburgh, PA), discipline where it is published, a match confidence, a 0 to 100 trust score, the reasons behind the score, and when each source was last refreshed.
Is this a background check or a consumer report?
No. Better Vetters reports public records. It is not a consumer reporting agency, and its output is not a consumer report under the Fair Credit Reporting Act. Do not use it for employment, credit, insurance, or tenant-screening decisions. See the Terms of Service.
FAQ
Data and coverage
Which places are covered?
Washington State, Texas (with Austin permits), New York City, Oregon, Connecticut, and Pittsburgh, Pennsylvania. Pennsylvania has no statewide contractor license, so Pennsylvania coverage is City of Pittsburgh licenses and permits only. Permit data is one city each in Washington, Texas, New York City, and Pennsylvania (Seattle, Austin, NYC, and Pittsburgh); Oregon and Connecticut are license-only. A request for any other state returns out_of_coverage and is not charged. See Coverage for the exact sources.
How should my agent act on a verdict?
Treat trusted and likely_ok as a positive signal and caution, high_risk, and needs_review as a reason for a human to look. Treat match.confidence below 0.8 as a possible match and confirm the returned license number or address. A fuzzy name-only match below 0.8 returns needs_review with the score capped at 50, so it never reads as clean. not_found means no record in the covered sources, which is not proof of a problem.
How fresh is the data?
It depends on the source. Most publishers update daily or nightly; the NYC license feed is weekly and the NYC charges feed is monthly. Oregon and Connecticut publish daily. Pittsburgh licenses update weekly and Pittsburgh permits daily. Responses include a data_freshness block with the last refresh and the publisher’s own update time for each source used.
Can I verify a contractor in California or Florida?
Not yet. Coverage is Washington, Texas, New York City, Oregon, Connecticut, and Pittsburgh, Pennsylvania. A request for any other state returns out_of_coverage and is not charged. Tell us which state you need on the feedback form.
How do I request a state or send feedback?
In writing. The feedback form has five short questions and takes about two minutes, or email james@fullyarmedmarketing.com with two or three sentences. There are no sales calls. If you leave an email, replies come only by email.
Does Better Vetters store the contractor details I search for?
Search inputs are used to answer the request. If you send an idempotency key, the inputs and result are stored temporarily so a retry can be replayed, and deleted after 90 days. Request logs do not include request bodies. See the Privacy Policy.
FAQ
Billing
What does a check cost?
$0.15 per check. Every new API key starts with 20 free checks, and you do not need a card to create one.
What happens when my credits run out?
The API returns HTTP 402 with a machine-readable body that includes the price, your balance, and that credit packs are coming soon. Nothing is charged for that request. Your free starter credits work now.
Are unused credits refundable?
No. All credit purchases are final and non-refundable, except where applicable law requires a refund, or to correct a duplicate or erroneous charge. Unused credits are not refundable. Credits do not expire while the account is active. Free starter credits have no cash value.
Is it safe to retry a request?
Yes. Send an Idempotency-Key header and a retried request returns the original result without a second charge.
Am I charged when a contractor is not found?
Yes, for now. A check that returns not_found or unknown still searched the records, so it costs $0.15. Requests for states outside coverage (out_of_coverage) and requests that fail with a server error are not charged.
How do I add credits?
Credit packs are coming soon. The $10, $50, and $200 packs are listed on this page, including bonus credit on the larger packs. Card checkout is not open yet. Your free starter credits work now. When packs are available, all credit purchases are final and non-refundable, except where applicable law requires a refund, or to correct a duplicate or erroneous charge.
FAQ
MCP and agents
Is there a hosted MCP endpoint?
Yes: https://api.bettervetters.com/mcp (streamable HTTP, Bearer API key). A local stdio server is also available. See the MCP server page.
How do I use it from an MCP client?
Point a streamable-HTTP MCP client at https://api.bettervetters.com/mcp with your API key as a Bearer token, or run the local stdio server. Both expose two tools, check_contractor and get_coverage. Setup steps are on the MCP server page and in the docs.
Run your first 20 checks free.
Create a key and send one request.
# Get a key (20 free checks, no card). The key is shown once.
curl -s -X POST https://api.bettervetters.com/v1/keys \
-H 'content-type: application/json' \
-d '{"label":"my-agent"}'