SalesCaddie API

Deals

Endpoint:https://api.salescaddie.dev

Deal intake and management endpoints

Submit a deal event

POST

https://api.salescaddie.dev

/v1/deals

Submit deal events from your CRM when deals close. We'll handle the rest automatically. Use the same deal.externalId to prevent duplicate campaigns.

Submit a deal event › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Submit a deal event › Request Body

dealobject · required
customerobject · required
salesRepobject · required

Submit a deal event › Responses

Deal event accepted for processing

dataobject · required

metaobject

POST /v1/deals

curl --request POST \
  --url https://api.salescaddie.dev/v1/deals \
  --header 'Authorization: <string>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "deal": {
    "externalId": "DEAL-12345",
    "closedAt": "2025-01-20T14:32:15Z",
    "value": 45000
  },
  "customer": {
    "firstName": "John",
    "lastName": "Smith",
    "phone": "+15551234567",
    "email": "[email protected]",
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "Austin",
      "state": "TX",
      "zipCode": "78701"
    }
  },
  "salesRep": {
    "externalId": "REP-789",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+15559876543",
    "email": "[email protected]"
  }
}
'

shell

Show example in

Request Body Example

{
  "deal": {
    "externalId": "DEAL-12345",
    "closedAt": "2025-01-20T14:32:15Z",
    "value": 45000
  },
  "customer": {
    "firstName": "John",
    "lastName": "Smith",
    "phone": "+15551234567",
    "email": "[email protected]",
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "Austin",
      "state": "TX",
      "zipCode": "78701"
    }
  },
  "salesRep": {
    "externalId": "REP-789",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+15559876543",
    "email": "[email protected]"
  }
}

json

application/json

Example Responses

{
  "data": {
    "idempotencyKey": "01KASZT8H0FPPZ2V37CM5KDE3M",
    "status": "accepted",
    "message": "Deal received successfully"
  },
  "meta": {
    "timestamp": "2025-11-24T03:51:42.460Z"
  }
}

json

application/json

Update a deal

PUT

https://api.salescaddie.dev

/v1/deals/{externalId}

Update an existing deal with new information. Typically used to add permit or installation dates after the initial submission. Include the optional Idempotency-Key header to safely retry if needed.

Update a deal › path Parameters

externalIdstring · required
External deal ID from your CRM (must match deal.externalId in payload)

Update a deal › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Idempotency-Keystring
Optional idempotency key for updates. If omitted, each update is processed independently.

Update a deal › Request Body

dealobject · required
customerobject · required
salesRepobject · required

Update a deal › Responses

Deal update accepted for processing

dataobject · required

metaobject

PUT /v1/deals/{externalId}

curl --request PUT \
  --url https://api.salescaddie.dev/v1/deals/:externalId \
  --header 'Authorization: <string>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "deal": {
    "externalId": "externalId",
    "closedAt": "2024-08-25T15:00:00Z",
    "value": 0,
    "permitDate": "2024-08-25T15:00:00Z",
    "installDate": "2024-08-25T15:00:00Z"
  },
  "customer": {
    "firstName": "firstName",
    "lastName": "lastName",
    "phone": "phone",
    "email": "[email protected]",
    "address": {
      "line1": "line1",
      "line2": "line2",
      "city": "city",
      "state": "state",
      "zipCode": "zipCode"
    }
  },
  "salesRep": {
    "externalId": "externalId",
    "firstName": "firstName",
    "lastName": "lastName",
    "phone": "phone",
    "email": "[email protected]"
  }
}
'

shell

Show example in

Request Body Example

{
  "deal": {
    "externalId": "externalId",
    "closedAt": "2024-08-25T15:00:00Z",
    "value": 0,
    "permitDate": "2024-08-25T15:00:00Z",
    "installDate": "2024-08-25T15:00:00Z"
  },
  "customer": {
    "firstName": "firstName",
    "lastName": "lastName",
    "phone": "phone",
    "email": "[email protected]",
    "address": {
      "line1": "line1",
      "line2": "line2",
      "city": "city",
      "state": "state",
      "zipCode": "zipCode"
    }
  },
  "salesRep": {
    "externalId": "externalId",
    "firstName": "firstName",
    "lastName": "lastName",
    "phone": "phone",
    "email": "[email protected]"
  }
}

json

Example Responses

{
  "data": {
    "idempotencyKey": "01KASZT8H0FPPZ2V37CM5KDE3M",
    "status": "accepted",
    "message": "Deal update received successfully",
    "externalId": "DEAL-12345"
  },
  "meta": {
    "timestamp": "2025-11-24T03:51:42.460Z"
  }
}

json

application/json

System

Submit a deal event

POST

https://api.salescaddie.dev

/v1/deals

Submit deal events from your CRM when deals close. We'll handle the rest automatically. Use the same deal.externalId to prevent duplicate campaigns.

Submit a deal event › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Submit a deal event › Request Body

dealobject · required
customerobject · required
salesRepobject · required

Submit a deal event › Responses

Deal event accepted for processing

dataobject · required

metaobject

curl --request POST \ --url https://api.salescaddie.dev/v1/deals \ --header 'Authorization: <string>' \ --header 'Content-Type: application/json' \ --data ' { "deal": { "externalId": "DEAL-12345", "closedAt": "2025-01-20T14:32:15Z", "value": 45000 }, "customer": { "firstName": "John", "lastName": "Smith", "phone": "+15551234567", "email": "[email protected]", "address": { "line1": "123 Main St", "line2": "Apt 4B", "city": "Austin", "state": "TX", "zipCode": "78701" } }, "salesRep": { "externalId": "REP-789", "firstName": "Jane", "lastName": "Doe", "phone": "+15559876543", "email": "[email protected]" } } '

{ "deal": { "externalId": "DEAL-12345", "closedAt": "2025-01-20T14:32:15Z", "value": 45000 }, "customer": { "firstName": "John", "lastName": "Smith", "phone": "+15551234567", "email": "[email protected]", "address": { "line1": "123 Main St", "line2": "Apt 4B", "city": "Austin", "state": "TX", "zipCode": "78701" } }, "salesRep": { "externalId": "REP-789", "firstName": "Jane", "lastName": "Doe", "phone": "+15559876543", "email": "[email protected]" } }

{ "data": { "idempotencyKey": "01KASZT8H0FPPZ2V37CM5KDE3M", "status": "accepted", "message": "Deal received successfully" }, "meta": { "timestamp": "2025-11-24T03:51:42.460Z" } }

Update a deal

PUT

https://api.salescaddie.dev

/v1/deals/{externalId}

Update an existing deal with new information. Typically used to add permit or installation dates after the initial submission. Include the optional Idempotency-Key header to safely retry if needed.

Update a deal › path Parameters

externalIdstring · required
External deal ID from your CRM (must match deal.externalId in payload)

Update a deal › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Idempotency-Keystring
Optional idempotency key for updates. If omitted, each update is processed independently.

Update a deal › Request Body

dealobject · required
customerobject · required
salesRepobject · required

Update a deal › Responses

Deal update accepted for processing

dataobject · required

metaobject

curl --request PUT \ --url https://api.salescaddie.dev/v1/deals/:externalId \ --header 'Authorization: <string>' \ --header 'Content-Type: application/json' \ --data ' { "deal": { "externalId": "externalId", "closedAt": "2024-08-25T15:00:00Z", "value": 0, "permitDate": "2024-08-25T15:00:00Z", "installDate": "2024-08-25T15:00:00Z" }, "customer": { "firstName": "firstName", "lastName": "lastName", "phone": "phone", "email": "[email protected]", "address": { "line1": "line1", "line2": "line2", "city": "city", "state": "state", "zipCode": "zipCode" } }, "salesRep": { "externalId": "externalId", "firstName": "firstName", "lastName": "lastName", "phone": "phone", "email": "[email protected]" } } '

{ "deal": { "externalId": "externalId", "closedAt": "2024-08-25T15:00:00Z", "value": 0, "permitDate": "2024-08-25T15:00:00Z", "installDate": "2024-08-25T15:00:00Z" }, "customer": { "firstName": "firstName", "lastName": "lastName", "phone": "phone", "email": "[email protected]", "address": { "line1": "line1", "line2": "line2", "city": "city", "state": "state", "zipCode": "zipCode" } }, "salesRep": { "externalId": "externalId", "firstName": "firstName", "lastName": "lastName", "phone": "phone", "email": "[email protected]" } }

{ "data": { "idempotencyKey": "01KASZT8H0FPPZ2V37CM5KDE3M", "status": "accepted", "message": "Deal update received successfully", "externalId": "DEAL-12345" }, "meta": { "timestamp": "2025-11-24T03:51:42.460Z" } }