Changelog

Track API changes, new features, and deprecations.

October 2026

v2Improved publication status descriptions
  • Improved publication status descriptions on GET /prospects and GET /prospects/:ticker. The API reference shows the current response shape.
  • Existing clients keep working.

October 2026

v2Published generations
  • GET /prospects returns a publication object for products that use published generations: generation_id, state, update_in_progress, latest_update_failed, previous_settings and warnings. Previous results stay listed while an update runs. Other products have no publication key.
  • Pass publication.generation_id as generation_id on later pages. If results were updated in between, the request returns 409 with reason "generation_unavailable": restart from offset 0 without generation_id.
  • assessment_status gains "unavailable" (analysis not available for this company in the current results), on rows and on include_children children. These rows carry null scores, rank after assessed and pending rows and before unassessed rows, and are excluded by a score floor.
  • GET /excerpts and POST /outreach return 409 with reason "analysis_unavailable" for those companies, before any credit is charged. GET /prospects/:ticker returns their facts-only shape.
  • Detail, excerpts and outreach responses carry publication.generation_id for products that use published generations.
  • A product with nothing published yet returns 200 with publication.state = "no_successful_generation" and unscored rows, not an empty list.
  • MCP server 2.12.0 supports all of the above.

October 2026

v2Nurture verdict and buying-signal weight
  • account_verdict on GET /prospects/:ticker gains the value "nurture": the company fits the product but no current trigger is evidenced. Treat unknown future values as non-actionable rather than failing. deprioritize is now only used for prospects with a deal score of 1 or 2.
  • GET /prospects/:ticker adds group_verdict: the verdict of the group prose when narrative_scope is "group" (where account_verdict is null). Same values as account_verdict.
  • A settled buying signal now adds more to the deal score: a potential opening adds 20 points and a strong buying opportunity adds 40 (previously 10 and 20). Scores update as each product is next processed, so deal_score can rise without new evidence.

October 2026

v2Complaint index by line
  • GET /prospects rows now carry complaints.by_line_of_business (latest report year, keyed like premium.by_line_of_business), each with report_year, total_complaints, complaint_index, complaint_index_status, contributing_entity_count and low_sample (fewer than 10 complaints). The family index per line is the NAIC formula over members reporting the same year. Top-level fields are unchanged.
  • New list parameters complaint_line, min_complaint_index and min_complaints. sort_by=complaint_index uses the selected line (a single supported lines_of_business value selects it by default); sector roll-ups and statement-only lines retain the all-lines index. Explicit unsupported complaint lines return 400. Per-line requests return 503 until the projection refresh completes.
  • GET /prospects/:ticker for parents with no NAIC cocode of their own (private parent placeholders, public parents) now returns complaints with scope: "family", the family rollup per year and line, and a by_entity breakdown, whether or not the member carriers are assessed. Observations gain low_sample.

August 2026

v2.1Facts-only detail
  • GET /prospects/:ticker and GET /excerpts no longer return 404 for companies that have not been assessed for the product. Detail returns the facts-only shape: assessment_status "unassessed", null scores, empty findings/excerpts, with company_info, premium, complaints, and hierarchy populated. Excerpts return an empty page (total_count 0). Every ticker visible in a list or hierarchy is now fetchable; 404 means unknown or ambiguous, never “not analysed yet”.

August 2026

v2Breaking — v1 removed
  • All endpoints moved to /api/v2. /api/v1 has been removed and returns 410 Gone with a JSON body naming the new base path. Update your base URL, and if you use the MCP server, upgrade it to 2.0.0 — 0.2.x targets v1 and stops working. Tool names, authentication, and configuration are unchanged.
  • Breaking: framework_category has been removed from the GET /excerpts query parameters and from every excerpt object, including excerpts embedded in prospect detail. Filter with min_impact_score and keyword instead.
  • Breaking: total_count is removed from GET /prospects; use total_groups (corporate families) and total_entities (companies inside them). (total_count on GET /excerpts is unrelated and unchanged.)
  • Breaking: GET /prospects, GET /prospects/:ticker, and GET /excerpts return 503 with { error: "projection_unavailable", reason } and a Retry-After header when the product's prospect data is rebuilding (rebuilding) or has not been rebuilt since a keywords edit (stale_keywords). Callers that read an empty v1 list as “nothing matched” must handle the error path.
  • GET /prospects now lists the full candidate universe, not only assessed companies. Rows carry assessment_status (assessed, pending_score, unassessed); unassessed rows have null deal_score / buying_signal_score and rank last under the default relevance ordering.
  • GET /prospects accepts new filters: assessment_status, entity_type, ownership, min_premium / max_premium, lines_of_business (any-match), min_licensed_states (0–50), states_licensed_in (all-match), q (name search, matching subsidiary names too), and include_children; plus sort_by / sort_dir with nulls-last semantics. Insurance filters are strict — a family with no premium data does not match a premium filter — and excluded_no_data_groups counts how many were dropped for lacking the data a filter required.
  • GET /prospects rows add NAIC premium summaries (with the report_years that contributed), family complaint summaries with complaint_index, lines_of_business, licensed_states, ownership, insurance_entity_types, and entity_count / matched_entity_count.
  • GET /prospects/:ticker adds company_info firmographics, entity-level premium and complaints (full per-year, per-line NAIC series, narrowable with report_year), hierarchy with child tickers you can pass straight back to the endpoint, narrative_scope, and excerpt_count. Embedded excerpts are capped at 20 (highest impact first); use GET /excerpts for the rest.
  • GET /products and GET /products/:id now return segment_targeting (all or selected) and target_segments: the insurance entity types a product sells to, with ownership, per-line premium bands, and licensed-footprint range. Segments are read-only; product setup stays in the UI.
  • Subsidiary tickers passed to the DealMap and outreach endpoints now resolve upward to the corporate family's DealMap (the response names the family) instead of failing. A generate that resolves to a cached family map is not charged.
  • PATCH /dealmap/node-top-pick is now documented (body { product_id, ticker, node_id, is_top_pick }). It was already implemented; it also gains an MCP tool, set_top_pick.

May 2026

v1Product visibility
  • GET /products and GET /products/:id now hide disabled products by default. Pass include_disabled=true to retrieve disabled product metadata.
  • Operational endpoints, including prospects, excerpts, outreach, and DealMap routes, continue to reject disabled product IDs.

March 2026

v1Initial release
  • GET /products and GET /products/:id — list and retrieve active products with keywords, sources, and industries. Disabled product metadata is available only through an explicit opt-in.
  • GET /prospects and GET /prospects/:ticker — list ranked prospects and get detailed company analysis.
  • GET /excerpts — search and filter evidence excerpts by impact score, framework category, and keywords.
  • GET /dealmap, POST /dealmap/generate, PATCH /dealmap/node-role — buying committee DealMap with AI-assigned stakeholder roles and org hierarchy.
  • POST /outreach — generate evidence-backed email and LinkedIn outreach messages.
  • Bearer token authentication with read and outreach scopes.
  • Per-key rate limiting with dedicated caps for DealMap generation and outreach.
  • Monthly credit system with per-plan allowances.
API ReferenceWorking with Products
Changelog | DealSurface Docs