Forecasting API

Add cold DM campaign forecasting to your own SaaS dashboard, internal tool, or reporting pipeline. One endpoint, JSON in, a full funnel forecast out — the same engine that powers the on-site calculator.

Authentication

Requests are authenticated with a bearer API key issued on the API plan. Keys are shown once at creation and are never stored in raw form. Pass the key in the Authorization header. Keep keys server-side — never embed them in client-side code.

Request

POST /api/v1/forecast — rates are percentages (0–100); seenRate and monthlyRepeat are optional.

POST https://www.colddmcalculator.com/api/v1/forecast
Authorization: Bearer cdm_live_xxxxxxxxxxxx_xxxxxxxx
Content-Type: application/json

{
  "dmsSent": 1500,
  "seenRate": 70,
  "replyRate": 5,
  "positiveReplyRate": 30,
  "bookingRate": 40,
  "closeRate": 20,
  "averageClientValue": 2000,
  "campaignCost": 500,
  "monthlyRepeat": true
}

Response

{
  "input": { "...": "echoed, validated input" },
  "forecast": {
    "estimatedSeen": 1050,
    "estimatedReplies": 52.5,
    "estimatedPositiveReplies": 15.75,
    "estimatedBookedCalls": 6.3,
    "estimatedClients": 1.26,
    "estimatedRevenue": 2520,
    "estimatedProfit": 2020,
    "roiMultiple": 5.04,
    "costPerBookedCall": 79.37,
    "costPerClient": 396.83,
    "revenuePerDm": 1.68,
    "revenuePerReply": 48,
    "breakEvenDms": 298,
    "annualizedPipelineValue": 30240,
    "riskScore": 16,
    "riskLevel": "low",
    "recommendations": ["..."]
  },
  "disclaimer": "Forecasts are estimates based on user-provided assumptions. Results are not guaranteed."
}

JavaScript example

const res = await fetch("https://www.colddmcalculator.com/api/v1/forecast", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.COLDDM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    dmsSent: 1500,
    replyRate: 5,
    positiveReplyRate: 30,
    bookingRate: 40,
    closeRate: 20,
    averageClientValue: 2000,
    campaignCost: 500,
  }),
});

const { forecast } = await res.json();
console.log(forecast.estimatedClients, forecast.roiMultiple);

Python example

import os
import requests

res = requests.post(
    "https://www.colddmcalculator.com/api/v1/forecast",
    headers={"Authorization": f"Bearer {os.environ['COLDDM_API_KEY']}"},
    json={
        "dmsSent": 1500,
        "replyRate": 5,
        "positiveReplyRate": 30,
        "bookingRate": 40,
        "closeRate": 20,
        "averageClientValue": 2000,
        "campaignCost": 500,
    },
    timeout=15,
)
res.raise_for_status()
forecast = res.json()["forecast"]
print(forecast["estimatedClients"], forecast["roiMultiple"])

Error codes

Status	Code	Meaning
400	invalid_json	Request body was not valid JSON.
401	unauthorized	Missing or invalid API key.
422	validation_failed	One or more inputs are invalid — see `details`.
429	rate_limited	Too many requests in a short window.
405	method_not_allowed	Use POST — GET is not supported.

Get API access

The API plan includes 25,000 forecasts per month, API key management, and priority support for $99/month.

Start API Manage API keys

Forecasts are estimates based on user-provided assumptions. Results are not guaranteed. The API forecasts campaign math — it does not send DMs or interact with any social platform.