Provider API schema and changelog
The published field contract for /api/provider/{slug}. Every field we serve is listed by name. Every field we have removed is listed by name, with its effective date.
entity_type, is still read internally by the admission gate but is no longer
returned. Deployed commit d722a6bf.
What the endpoint returns
GET /api/provider/{slug} returns { "success": true, "provider": { … } }.
The provider object contains the 38 provider fields below, plus three
review aggregates (average_rating, review_count, reviews) that are
computed rather than stored on the provider record. Fields with no value for a given provider are
returned as null; they are not omitted.
The response body is built by selecting the named fields, not by deleting unwanted ones. A field that is not on this page is not served, and adding a column to our database does not add it to this API.
Served fields (38)
Identity and directory content (17)
| Field | Notes |
|---|---|
id, slug | Stable identifiers. slug is the URL key. |
company_name | Provider name. |
category, categories, super_category | Category assignment and its parent grouping. |
website, phone | Public contact points. |
address, city, state, city_slug, state_abbr | Location, plus the URL-safe forms. |
description | Directory description. |
services_tags, specialties | Service and specialty tags. |
practice_size_fit | Practice sizes the provider serves. |
Listing status and profile completeness (4)
| Field | Notes |
|---|---|
verified | Verification flag. Also part of the public MCP tool contract. |
quality_score | Profile completeness, 0-100: points for listing fields present (website, phone, description, services, location, source, firmographics). Not a quality or reputation judgement. Rendered on the public provider page as Profile Completeness and part of the MCP tool contract; a value of 0 means the row was never scored and is not displayed as a score. |
featured | Paid placement. Disclosed deliberately: a caller has a legitimate interest in knowing a listing is promoted. |
claimed | Whether the provider has claimed the listing. The claim flow is itself public. |
Third-party reputation (2)
| Field | Notes |
|---|---|
google_rating, google_review_count | Already public at the source. |
Firmographics (6)
| Field | Notes |
|---|---|
apollo_employee_count, apollo_founded_year, apollo_annual_revenue, apollo_industry, apollo_funding, apollo_linkedin_url | Business attributes from a third-party firmographic feed. |
Enriched corpus (6)
| Field | Notes |
|---|---|
enriched_description | Extracted description. |
enriched_services_tags, enriched_certifications, enriched_practice_size_fit | Extracted service, certification and practice-size detail. |
enriched_locations | Locations served. Constrained to a fixed grammar. |
enriched_founding_year | Founding year, where extracted. |
Provenance and grade (3)
| Field | Values |
|---|---|
extraction_confidence | Closed set: high, medium, low, or null. |
extraction_grounded_in | Closed set: site, both, or null. Values outside the published set are returned as null rather than passed through. |
tier1_grade | Closed set: A, B, or null. Also a caller-supplied filter on the MCP search tool. |
Removed fields (20) — effective 2026-09-10
These fields were served before 2026-09-10 and are no longer returned. They are named here so the change is a published contract rather than a silent absence. All are internal operational values; none is directory content.
| Removed field | Why |
|---|---|
source | Internal ingestion label — an open-ended internal string that also named our data vendors to any caller. |
tier | Internal listing bookkeeping. Held a single value across the whole corpus, so it conveyed nothing while disclosing our commercial tiering. |
claimed_at | Timestamp of a private business event. claimed answers the public question. |
reputation_score, demand_score | Internal ranking inputs. Publishing a ranking input is an invitation to game it, and neither was rendered anywhere. |
indexed, no_nexus | Our own indexing decisions. The effect is public; the verdict is not. |
merged_into, parent_slug | Internal de-duplication pointers. The redirects they drive still happen server-side. |
tier1_member | The internal boolean behind tier1_grade. The grade is the published signal. |
extraction_fetch_mode, extracted_at | Extraction-run telemetry and cadence. |
liveness_status, liveness_checked_at, last_alive_at, refreshed_at | Our liveness-probe verdicts and probe cadence. |
apollo_enriched_at | Vendor-feed run timestamp. Internal cadence. |
submitted_at, created_at, updated_at | Our row write timestamps. These are not a content-freshness signal about the provider. |
Fields that are never served
entity_type is read by the admission gate that decides whether a provider is served at all. It is
queried and never returned.
Five fields are withheld unconditionally and are not part of any tier of this API:
edit_token, claimed_email, provenance,
apollo_short_description and liveness_evidence.
How changes are published
A field added to or removed from the served set is announced on this page with its effective date. We do not remove a field from the response without naming it here.
Higher volume or bulk access: see Data Licensing. Programmatic access options: see API Access.