API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. Create and manage API keys in your portal settings.

curl https://digitaldawn.ai/api/v1/leads \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Endpoints

Base URL: https://digitaldawn.ai/api/v1

All responses use a consistent envelope:

// Success
{ "data": { ... }, "meta": { "total": 42, "page": 1, "perPage": 20 } }

// Error
{ "error": "Descriptive error message." }

Leads

{
  "name": "Jane Smith",
  "businessName": "Smith HVAC",
  "email": "jane@smithhvac.com",
  "phone": "+1-555-555-0100",   // optional
  "challenge": "We lose leads when we're out on jobs."
}

{ "status": "booked" }  // one of: new, contacted, booked, closed

{
  "data": [
    {
      "id": "3f1a2b...",
      "name": "Jane Smith",
      "businessName": "Smith HVAC",
      "email": "jane@smithhvac.com",
      "phone": "+1-555-555-0100",
      "challenge": "We lose leads when we're out on jobs.",
      "status": "new",
      "source": "web_form",
      "aiResponse": "Hi Jane, thanks for reaching out...",
      "createdAt": "2026-04-01T14:22:00Z",
      "updatedAt": "2026-04-01T14:22:05Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "perPage": 20 }
}

Events

{
  "data": [
    {
      "id": "9c3d...",
      "leadId": "3f1a2b...",
      "eventType": "email.sent",
      "status": "success",
      "meta": { "to": "jane@smithhvac.com", "subject": "Re: AI automation for Smith HVAC" },
      "createdAt": "2026-04-01T14:22:06Z"
    }
  ],
  "meta": { "total": 5, "page": 1, "perPage": 20 }
}

Webhooks

Register an HTTPS endpoint to receive real-time event payloads. Webhooks are delivered asynchronously with up to 3 retries on failure. You can also manage webhooks from your portal settings.

{
  "url": "https://your-server.com/webhooks/dd",
  "events": ["lead.created", "email.sent"]  // omit or [] to receive all events
}

{
  "data": {
    "id": "7e9f...",
    "url": "https://your-server.com/webhooks/dd",
    "events": ["lead.created", "email.sent"],
    "status": "active",
    "secret": "a3f9b2c1...",  // store this — it will not be returned again
    "createdAt": "2026-04-01T10:00:00Z"
  }
}

Webhook event types

POST https://your-server.com/webhooks/dd
Content-Type: application/json
X-DD-Event: lead.created
X-DD-Signature: sha256=a3f9b2c1d8e7...

{
  "event": "lead.created",
  "tenantId": "abc123...",
  "timestamp": "2026-04-01T14:22:00Z",
  "data": {
    "leadId": "3f1a2b...",
    "name": "Jane Smith",
    "businessName": "Smith HVAC",
    "email": "jane@smithhvac.com",
    "phone": "+1-555-555-0100",
    "challenge": "We lose leads when we're out on jobs."
  }
}

Signature verification

Every delivery includes an X-DD-Signatureheader. Verify it using your webhook's signing secret (returned once at registration time).

// Node.js example
import { createHmac } from 'crypto'

function verifyWebhook(
  rawBody: string,
  signature: string,  // value of X-DD-Signature header
  secret: string
): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
  return expected === signature
}

Rate limits & errors

The API does not currently enforce a hard rate limit, but per-account AI response and email quotas apply based on your plan tier. Exceeding them returns a 503.

TypeScript SDK

The official @digitaldawn/sdk package wraps the REST API with full TypeScript types and a built-in webhook verification helper.

npm install @digitaldawn/sdk

import { DigitalDawn } from '@digitaldawn/sdk'

const dd = new DigitalDawn({ apiKey: 'sk_live_your_api_key' })

// List leads
const { data, meta } = await dd.leads.list({ status: 'new', page: 1 })

// Create a lead
const lead = await dd.leads.create({
  name: 'Jane Smith',
  businessName: 'Smith HVAC',
  email: 'jane@smithhvac.com',
  challenge: 'We lose leads when out on jobs.',
})

// Update status
await dd.leads.updateStatus(lead.data.id, 'booked')

// Manage webhooks
const webhook = await dd.webhooks.create({
  url: 'https://your-server.com/webhooks/dd',
  events: ['lead.created', 'email.sent'],
})
// webhook.data.secret — store this, returned once only

// Verify a webhook payload using the SDK helper
const isValid = dd.webhooks.verify(rawBody, req.headers['x-dd-signature'], secret)
if (!isValid) return res.status(401).end()

const event = dd.webhooks.parse(rawBody)
// event is fully typed: LeadCreatedEvent | LeadStatusChangedEvent | ...

const dd = new DigitalDawn({
  apiKey: 'sk_live_...',
  baseUrl: 'http://localhost:3000/api/v1',
})