API Reference

Complete reference for every DealSurface REST API endpoint.

All endpoints require a Bearer token in the Authorization header. Rate-limit headers are included on every response.

GET/api/v1/productsscope: readFree

List active products for the authenticated team. Disabled product metadata is hidden unless explicitly requested.

Query parameters

Parameter	Type	Description
`include_disabled`	`boolean`= false	Include disabled product metadata. Defaults to false.

Response

{
  "products": [
    {
      "product_id": 12,
      "name": "Cyber Insurance Platform",
      "description": "End-to-end cyber risk assessment...",
      "created_at": "2026-01-15T10:30:00Z",
      "is_active": true,
      "keywords": [
        { "keyword_id": 1, "name": "cyber risk", "auto_extracted": false }
      ],
      "sources": [
        { "source_id": 5, "url": "https://example.com", "title": "Product page", "source_type": "url" }
      ],
      "industries": [
        { "industry_name": "Fire, Marine & Casualty Insurance", "industry_description": "...", "industry_code": "6331" }
      ]
    }
  ]
}

Examples

curl https://dealsurface.com/api/v1/products \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY"

GET/api/v1/products/:productIdscope: readFree

Get detailed information about a specific active product. Disabled product metadata is hidden unless explicitly requested.

Path parameters

Parameter	Type	Description
`productId`required	`integer`	The product ID (positive integer).

Query parameters

Parameter	Type	Description
`include_disabled`	`boolean`= false	Allow returning disabled product metadata. Defaults to false.

Response

Same shape as a single product from List Products, wrapped in { product: ... }.

Examples

curl https://dealsurface.com/api/v1/products/12 \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY"

Returns 404 if the product doesn't exist or belongs to a different team, or if it is disabled andinclude_disabledis not true. Operational endpoints remain active-only.

GET/api/v1/prospectsscope: readFree

List assessed companies with deal scores for a product.

Query parameters

Parameter	Type	Description
`product_id`required	`integer`	Product to get prospects for.
`min_deal_score`	`integer`	Minimum deal score filter (1-5). `12345`
`min_buying_signal`	`float`	Minimum buying signal score (0.0-1.0).
`limit`	`integer`= 100	Max results to return.
`offset`	`integer`= 0	Pagination offset.

Response

{
  "prospects": [
    {
      "ticker": "TRV",
      "company_name": "Travelers Companies Inc",
      "deal_score": 5,
      "rank": 1,
      "rank_total": 142
    }
  ],
  "total_count": 142,
  "limit": 100,
  "offset": 0
}

Examples

curl "https://dealsurface.com/api/v1/prospects?product_id=12&min_deal_score=4&limit=10" \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY"

GET/api/v1/prospects/:tickerscope: readFree

Full prospect analysis for a specific company and product.

Path parameters

Parameter	Type	Description
`ticker`required	`string`	Company ticker symbol (alphanumeric, max 10 characters, dots allowed).

Query parameters

Parameter	Type	Description
`product_id`required	`integer`	Product context for this prospect analysis.

Response

{
  "ticker": "TRV",
  "company_name": "Travelers Companies Inc",
  "deal_score": 5,
  "rank": 1,
  "rank_total": 142,
  "findings_summary": "Travelers is actively investing in...",
  "recommendation_summary": "Strong fit for cyber insurance...",
  "key_opportunity": "CEO cited cyber as top growth area...",
  "primary_challenge": "Legacy claims systems...",
  "impact_score_distribution": { "5": 3, "4": 8, "3": 12, "2": 5, "1": 2 },
  "findings": [
    {
      "finding_id": 1,
      "text": "Travelers announced a $200M technology...",
      "evidence_excerpt_ids": [101, 102]
    }
  ],
  "excerpts": [
    {
      "excerpt_id": 101,
      "text": "We are investing significantly in...",
      "impact_score": 5,
      "framework_category": "Strategic Intent",
      "source": { "name": "Q3 2025 Earnings Call", "date": "2025-10-28" },
      "pain_points": ["technology modernization", "cyber exposure"],
      "sales_summary": "CEO emphasizes cyber investment priority",
      "buying_signal_present": true
    }
  ]
}

Examples

curl "https://dealsurface.com/api/v1/prospects/TRV?product_id=12" \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY"

GET/api/v1/excerptsscope: readFree

Search and filter evidence excerpts for a prospect and product.

Query parameters

Parameter	Type	Description
`product_id`required	`integer`	Product context.
`ticker`required	`string`	Company ticker symbol.
`min_impact_score`	`integer`	Minimum impact score (1-5). `12345`
`framework_category`	`string`	Filter by framework category. `Strategic IntentMetric IntentMarket Topics`
`keyword`	`string`	Filter excerpts where pain_points contain this keyword (case-insensitive, max 200 chars).
`limit`	`integer`= 50	Max results.
`offset`	`integer`= 0	Pagination offset.

Response

{
  "excerpts": [
    {
      "excerpt_id": 101,
      "text": "We are investing significantly in...",
      "impact_score": 5,
      "framework_category": "Strategic Intent",
      "source": { "name": "Q3 2025 Earnings Call", "date": "2025-10-28" },
      "pain_points": ["technology modernization"],
      "sales_summary": "CEO emphasizes cyber investment priority",
      "buying_signal_present": true
    }
  ],
  "total_count": 30,
  "limit": 50,
  "offset": 0
}

Examples

curl "https://dealsurface.com/api/v1/excerpts?product_id=12&ticker=TRV&min_impact_score=4&framework_category=Strategic+Intent" \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY"

GET/api/v1/dealmapscope: readFree

Read the current buying committee DealMap for a prospect company and product. Returns stakeholders with AI-assigned roles, org hierarchy edges, and a buying committee summary.

Query parameters

Parameter	Type	Description
`product_id`required	`integer`	Product context.
`ticker`required	`string`	Company ticker symbol.

Response

{
  "status": "ready",
  "chart": {
    "id": "abc-123",
    "generated_at": "2026-04-01T10:00:00Z",
    "expires_at": "2026-05-01T10:00:00Z",
    "company_name": "Travelers Companies Inc",
    "node_count": 45,
    "relevant_node_count": 12
  },
  "stakeholders": [
    {
      "node_id": "n-001",
      "full_name": "Jane Smith",
      "title": "Chief Information Officer",
      "level": "c_suite",
      "level_label": "C-Suite",
      "linkedin_url": "https://linkedin.com/in/janesmith",
      "work_email": null,
      "manager_name": null,
      "stakeholder_role": "Economic Buyer",
      "stakeholder_role_source": "generated",
      "annotation_score": 9,
      "annotation_reason": "Oversees technology budget...",
      "is_top_pick": true,
      "top_pick_source": "generated"
    }
  ],
  "edges": [
    { "from_node_id": "n-001", "to_node_id": "n-002", "relationship": "manages" }
  ],
  "buying_committee_summary": {
    "economic_buyer": "Jane Smith",
    "decision_maker": "Bob Johnson",
    "champion": null,
    "executive_sponsor": null,
    "evaluator": "Alice Wong",
    "blockers": []
  }
}

Returns "status": "empty" if no DealMap has been generated yet. Call POST /dealmap/generate first.

Examples

curl "https://dealsurface.com/api/v1/dealmap?product_id=12&ticker=TRV" \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY"

POST/api/v1/dealmap/generatescope: readscope: outreach0-10 credits

Generate or refresh the buying committee DealMap for a prospect. Maps the org structure and assigns stakeholder roles using AI analysis. Credits charged only when fresh org-chart data is fetched.

Request body

Parameter	Type	Description
`product_id`required	`integer`	Product context.
`ticker`required	`string`	Company ticker symbol.
`force_refresh`	`boolean`= false	Force fresh org chart fetch, bypassing cache. Consumes credits.

force_refresh costs credits

Setting force_refresh: true always charges credits because it triggers a fresh org-chart fetch. Only use this if you need up-to-date organizational data and the cached results are known to be stale.

Response

{
  "status": "ready",
  "chart": {
    "id": "abc-123",
    "generated_at": "2026-04-01T10:00:00Z",
    "expires_at": "2026-05-01T10:00:00Z",
    "company_name": "Travelers Companies Inc",
    "node_count": 45,
    "relevant_node_count": 12
  },
  "stakeholders": [...],
  "edges": [...],
  "buying_committee_summary": {
    "economic_buyer": "Jane Smith",
    "decision_maker": "Bob Johnson",
    "champion": null,
    "executive_sponsor": null,
    "evaluator": "Alice Wong",
    "blockers": []
  },
  "generation_source": "org_fresh",
  "credits_charged": true,
  "credits_operation": "prospect_org_chart_annotation"
}

Credit behavior

generation_source	Credits charged
org_fresh	Yes (10 credits)
org_cached	No
annotation_only	No

Examples

curl -X POST https://dealsurface.com/api/v1/dealmap/generate \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": 12, "ticker": "TRV"}'

PATCH/api/v1/dealmap/node-rolescope: readscope: outreachFree

Override the AI-assigned stakeholder role for a specific person on the buying committee DealMap. This is a team-wide override visible to all team members.

Request body

Parameter	Type	Description
`product_id`required	`integer`	Product context.
`ticker`required	`string`	Company ticker symbol.
`node_id`required	`string`	The node_id from the DealMap stakeholders.
`stakeholder_role`required	`string`	The corrected stakeholder role. `Economic BuyerDecision MakerChampionExecutive SponsorEvaluatorEnd UserProcurement / Legal ReviewerBlockerIrrelevant`

Response

{
  "success": true,
  "node_id": "n-001",
  "stakeholder_role": "Decision Maker"
}

Examples

curl -X PATCH https://dealsurface.com/api/v1/dealmap/node-role \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": 12, "ticker": "TRV", "node_id": "n-001", "stakeholder_role": "Decision Maker"}'

POST/api/v1/outreachscope: readscope: outreach1 credit

Generate an evidence-backed outreach message for a prospect. Consumes 1 credit per successful request.

Request body

Parameter	Type	Description
`product_id`required	`integer`	Product context.
`ticker`required	`string`	Company ticker symbol.
`platform`required	`string`	Target platform for the message. `emaillinkedin`
`tone`required	`string`	Desired tone. `hard_sellhelpfulneutral`
`length`	`string`= typical	Desired length. `shortertypicallonger`
`selected_lead`	`SelectedLead`	A full lead object (from /leads response) to personalize the message for. Takes precedence over lead_selector.
`lead_selector`	`object`	Selector to resolve a stakeholder from cached DealMap results. One of: { node_id: string }, { level: "manager"\|"director"\|"vp"\|"c_suite" }, { full_name: string, level: string }, or { stakeholder_role: string }.

Lead targeting

You can pass either selected_lead (the full lead object) or lead_selector (to resolve a lead from cached results). If both are provided, selected_lead takes precedence. If neither is provided, outreach is generated without personalization for a specific contact.

Response

{
  "subject": "Helping Travelers strengthen cyber risk assessment",
  "body": "Hi Jane,\n\nI noticed Travelers has been investing...",
  "platform": "email",
  "tone": "helpful",
  "length": "typical",
  "used_excerpt_ids": [101, 102, 105],
  "selected_lead": {
    "full_name": "Jane Smith",
    "title": "Chief Information Officer",
    "level": "c_suite"
  },
  "selected_lead_note": null
}

The used_excerpt_ids array indicates which evidence excerpts were used to ground the message. Cross-reference with the Excerpts endpoint to verify sources.

Examples

curl -X POST https://dealsurface.com/api/v1/outreach \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 12,
    "ticker": "TRV",
    "platform": "email",
    "tone": "helpful",
    "lead_selector": { "level": "c_suite" }
  }'

Error Handling Changelog