Crafting Outreach

Generate outreach

The outreach endpoint generates a message grounded in real evidence from the prospect's public filings and earnings calls. Every request consumes 1 credit.

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

Product defaults and template selection

Omit template_key to use the product's effective default. Template listing is free and requires the same read + outreach scopes as template-aware generation. Entries report their type and credit cost: deterministic static messages are free, while generation prompts and static messages with an AI hook cost one credit on success. Creation, editing, product assignment, and default changes are managed under Outreach → Templates in the app, not through API v2.

curl "https://dealsurface.com/api/v2/outreach/templates?product_id=12" \
  -H "Authorization: Bearer $DEALSURFACE_API_KEY"

Use system_default to explicitly select the built-in template. Successful responses includetemplate_used with the exact key, version, type, source, and resolution path.

Platform, voice, and length

Choose the platform for the message. Voice, structure, and length come from the selected template's instructions, so write them there (for example “four short lines, under 50 words, peer to peer”). The retired tone and length fields are ignored; requests that still send them get a deprecation_notice in the response and a Deprecation header. A future release will reject them, so remove them now.

Targeting a specific stakeholder

There are three ways to personalize outreach for a specific contact:

1. Pass the full stakeholder object

If you already have a stakeholder from the /dealmap endpoint, pass it directly:

{
  "product_id": 12,
  "ticker": "TRV",
  "platform": "email",
  "selected_lead": {
    "full_name": "Jane Smith",
    "title": "Chief Information Officer",
    "level": "c_suite",
    "linkedin_url": "https://linkedin.com/in/janesmith"
  }
}

2. Use a lead selector

Let the API resolve the best stakeholder from the cached DealMap:

{
  "product_id": 12,
  "ticker": "TRV",
  "platform": "email",
  "lead_selector": { "level": "c_suite" }
}

{
  "product_id": 12,
  "ticker": "TRV",
  "platform": "email",
  "lead_selector": { "full_name": "Jane Smith", "level": "c_suite" }
}

{
  "product_id": 12,
  "ticker": "TRV",
  "platform": "email",
  "lead_selector": { "stakeholder_role": "Economic Buyer" }
}

3. No lead targeting

Omit both fields to generate generic outreach for the company without personalizing for a specific contact.

Verifying evidence sources

The response includes used_excerpt_ids — the evidence excerpts that grounded the message. Cross-reference with the excerpts endpoint to verify the claims in the generated copy.