Documentation

Copy page

Core Concepts

Understanding these key concepts will help you integrate effectively with the SalesCaddie API.

---

Preventing Duplicates

We automatically prevent duplicate campaigns using your deal ID:

• Creating deals: Use the same deal.externalId to prevent duplicates. Re-sending a deal with the same ID won't create a second campaign.
• Updating deals: Add the Idempotency-Key header to safely retry failed requests.

Using Idempotency Keys

Include the Idempotency-Key header when retrying updates:

Code
 
Idempotency-Key: DEAL-12345-UPDATE-1

Best practice: Use your deal ID or a combination of deal ID and operation. Avoid random values that change on each retry.

---

Rate Limits

Rate limiting is not enforced yet. We will publish limits and headers when they are enabled. For now, design your client to handle 429 Too Many Requests with backoff so you are ready when limits go live.

---

Error Handling

All API errors follow the RFC 7807 standard shape for consistent, machine-readable error responses.

Error Response Format

Code
 
{
  "type": "https://httpstatuses.com/400",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid phone number format for customer.phone",
  "instance": "/v1/deals"
}

Fields:

• type: URI reference identifying the error type
• title: Human-readable error summary
• status: HTTP status code
• detail: Specific details about this error occurrence (may be omitted)
• instance: The API endpoint that generated the error

Common Status Codes

Code	Meaning	When It Happens
202	Accepted	Request successfully queued
400	Bad Request	Invalid data format or validation failure
401	Unauthorized	Missing or invalid API key
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

---

Phone Numbers

Phone numbers are normalized to E.164 format before processing. Preferred input is already E.164 (e.g., +15551234567). U.S. formats like (555) 123-4567 are accepted and converted to +15551234567. Invalid numbers will be rejected with a 400 Bad Request.

---

Next Steps

→ Review Authentication best practices

→ Explore the API Reference for detailed endpoint documentation

→ Need help? Check out Support