REST API
The DealSurface REST API lets you programmatically access prospect intelligence, filter carriers by their book of business, map buying committees, and craft personalized outreach.
Base URL
All API requests are made to the following base URL:
https://dealsurface.com/api/v2Authentication
Authenticate by passing your API key as a Bearer token in the Authorization header. API keys can be created from Settings → API Keys in your dashboard.
curl https://dealsurface.com/api/v2/products \
-H "Authorization: Bearer ds_live_..."See the Authentication guide for details on scopes and key management.
Endpoints
| Method | Path | Description | Credits |
|---|---|---|---|
| GET | /products | List active products and their target segments | Free |
| GET | /products/:id | Get an active product | Free |
| GET | /prospects | List ranked prospects with premium and complaint data | Free |
| GET | /prospects/:ticker | Get prospect detail, including corporate family | Free |
| GET | /excerpts | Search evidence excerpts | Free |
| GET | /dealmap | Get buying committee DealMap | Free |
| POST | /dealmap/generate | Generate DealMap | 0-10 |
| PATCH | /dealmap/node-role | Override stakeholder role | Free |
| PATCH | /dealmap/node-top-pick | Set the top pick for a role | Free |
| POST | /outreach | Generate outreach copy | 1 |
Prospects are corporate families
A prospect returned by /prospects is a corporate family, not a single legal entity. A large insurer is dozens of licensed subsidiaries, so entity-level rows would fill your first page with one company. Each row reports entity_count for the companies in the family and matched_entity_count for how many satisfied your filters. To reach an individual subsidiary, call /prospects/:ticker and use an identifier from hierarchy.children.
The list contains the full candidate universe for a product — every company family, whether or not we have assessed it yet — exactly like the web app. Each row is labeled with assessment_status (assessed, pending_score, or unassessed). Unassessed rows carry null scores and rank last under the default ordering — present, never hidden — so “how big is this market?” and “who should I call first?” are the same list read at different depths.
Versioning
The current API version is v2, included in the URL path. v1 has been removed — requests to /api/v1 return 410 Gone with a JSON body naming /api/v2 and linking the changelog. Breaking changes are introduced in a new version number; non-breaking additions (new fields, new optional parameters) may be added to v2 at any time, so parse responses tolerantly.
If you are moving from v1, see the Changelog for every difference that may require code changes.
Content type
All responses are JSON. POST endpoints accept application/json request bodies.