Documentation

Getting Started

This API is designed for custom CRM integrations that trigger automated campaign generation based on deal closure events. When a deal closes in your CRM, send us the deal data and campaigns are automatically created.

Questions? Contact our engineering team at [email protected]

Overview

The SalesCaddie API provides a small surface area focused on deal intake:

/health (public): basic liveness check
/v1/me (auth): quick API key test that returns your company slug
POST /v1/deals (auth): submit a new deal
PUT /v1/deals/\{externalId\} (auth): update an existing deal using the same payload shape

All responses are wrapped in a JSON envelope: { "data": { ... }, "meta": { "timestamp": "..." } }.

Quick Start

Step 1: Get Your API Key

Please reach out to us at [email protected] to receive your production API credentials. We're currently working on a self-service portal—stay tuned!

Step 2: API Endpoint

Production Environment:

Code
 
https://api.salescaddie.dev

Step 3: Make Your First Request

Here's a quick example of creating a campaign when a deal closes:

Code
 
curl -X POST https://api.salescaddie.dev/v1/deals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deal": {
      "externalId": "DEAL-12345",
      "closedAt": "2025-01-20T14:32:15Z",
      "value": 45000.0
    },
    "customer": {
      "firstName": "Jane",
      "lastName": "Smith",
      "phone": "+15551234567",
      "email": "[email protected]",
      "address": {
        "line1": "123 Main Street",
        "city": "Austin",
        "state": "TX",
        "zipCode": "78701"
      }
    },
    "salesRep": {
      "externalId": "REP-789",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+15559876543",
      "email": "[email protected]"
    }
  }'

Expected Response (202 Accepted):


Code
 
{
  "data": {
    "idempotencyKey": "your-company-slug:DEAL-12345",
    "status": "accepted",
    "message": "Deal received successfully"
  },
  "meta": {
    "timestamp": "2025-01-20T14:32:15.000Z"
  }
}

That's it! We'll take care of the rest automatically.

Idempotency

Use the same deal.externalId to update an existing deal instead of creating a duplicate. For updates, you can also use the Idempotency-Key header to safely retry.

What's Next?

→ Learn about Authentication and API keys

→ Understand Core Concepts like idempotency and phone formatting

→ Explore the API Reference for detailed endpoint documentation

→ Need help? Check out Support

Last modified on November 24, 2025

Authentication

Overview

The SalesCaddie API provides a small surface area focused on deal intake:

/health (public): basic liveness check

/v1/me (auth): quick API key test that returns your company slug

POST /v1/deals (auth): submit a new deal

PUT /v1/deals/\{externalId\} (auth): update an existing deal using the same payload shape

All responses are wrapped in a JSON envelope: { "data": { ... }, "meta": { "timestamp": "..." } }.

Quick Start

Step 1: Get Your API Key

Please reach out to us at [email protected] to receive your production API credentials. We're currently working on a self-service portal—stay tuned!

Step 2: API Endpoint

Production Environment:

Code

https://api.salescaddie.dev

Step 3: Make Your First Request

Here's a quick example of creating a campaign when a deal closes:

Code

curl -X POST https://api.salescaddie.dev/v1/deals \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "deal": { "externalId": "DEAL-12345", "closedAt": "2025-01-20T14:32:15Z", "value": 45000.0 }, "customer": { "firstName": "Jane", "lastName": "Smith", "phone": "+15551234567", "email": "[email protected]", "address": { "line1": "123 Main Street", "city": "Austin", "state": "TX", "zipCode": "78701" } }, "salesRep": { "externalId": "REP-789", "firstName": "John", "lastName": "Doe", "phone": "+15559876543", "email": "[email protected]" } }'

Expected Response (202 Accepted):

Code

{
  "data": {
    "idempotencyKey": "your-company-slug:DEAL-12345",
    "status": "accepted",
    "message": "Deal received successfully"
  },
  "meta": {
    "timestamp": "2025-01-20T14:32:15.000Z"
  }
}

That's it! We'll take care of the rest automatically.

Idempotency

Use the same deal.externalId to update an existing deal instead of creating a duplicate. For updates, you can also use the Idempotency-Key header to safely retry.