{"openapi":"3.1.0","info":{"title":"Better Vetters API","summary":"Vet every contractor in one call.","description":"Better Vetters is a pay-per-call contractor verification API for AI agents, built only from official open-data sources (state licence boards and city permit portals). Returns licence status, permit activity, discipline where published, a match confidence, an overall trust score with reasons, and data freshness timestamps.\n\n**Auth**: `Authorization: Bearer <api key>` (get one free from `POST /v1/keys`, it includes starter credits). New keys use the prefix `bv_live_`; existing `cc_live_` keys keep working.\n**Billing**: each `POST /v1/contractor/check` costs the configured price (default $0.15). When credits run out the API answers `402` with an x402-style payment body. Free starter credits have no cash value. Credits do not expire while the account is active. 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.\n\nNot legal advice or a consumer report. Public records can be stale or incomplete; always read `data_freshness` and `match.confidence`.","contact":{"name":"James Russell","url":"https://bettervetters.com/","email":"james@fullyarmedmarketing.com"},"version":"0.1.0"},"servers":[{"url":"https://api.bettervetters.com"}],"paths":{"/v1/coverage":{"get":{"tags":["meta"],"summary":"What jurisdictions, sources, record counts and freshness are covered (free, no key)","operationId":"coverage_v1_coverage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/keys":{"post":{"tags":["billing"],"summary":"Create an API key with free starter credits (shown once)","operationId":"create_key_v1_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/credits":{"get":{"tags":["billing"],"summary":"Balance and recent ledger entries","operationId":"credits_v1_credits_get","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/credits/checkout":{"post":{"tags":["billing"],"summary":"Start a Stripe Checkout for a credit pack (paused until CHECKOUT_ENABLED is true)","operationId":"checkout_v1_credits_checkout_post","parameters":[{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/contractor/check":{"post":{"tags":["check"],"summary":"Vet a contractor (billed per call)","operationId":"check_v1_contractor_check_post","parameters":[{"name":"idempotency-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"402":{"description":"Insufficient credits. Body is an x402-style payment-required document."},"401":{"description":"Missing or invalid API key"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CheckRequest":{"properties":{"name":{"type":"string","maxLength":200,"minLength":2,"title":"Name","description":"Business or contractor name as the caller knows it.","examples":["Seattle Roofing Co"]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"Two-letter US state (WA, TX, NY). Narrows the search; strongly recommended.","examples":["WA"]},"city":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"City","description":"City, used as a secondary matching signal.","examples":["Seattle"]},"license_number":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"License Number","description":"Licence number if known; an exact hit gives high confidence."},"phone":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"title":"Phone","description":"Business phone; matched against the licence record."},"website":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Website","description":"Business website; its domain is compared to the matched name. Never fetched."}},"type":"object","required":["name"],"title":"CheckRequest"},"CheckoutRequest":{"properties":{"pack":{"type":"string","title":"Pack","description":"One of the pack ids from GET /v1/coverage -> pricing.credit_packs","examples":["pack_10"]}},"type":"object","required":["pack"],"title":"CheckoutRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KeyRequest":{"properties":{"label":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Label"},"email":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Email","description":"Optional, for receipts and low-balance notices."}},"type":"object","title":"KeyRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}