Guides
Start typing to search…

Getting Started

This page will help you get started with Sure Send. You'll be up and running in a jiffy!

Getting Started with Sure Send CRM Partner API

Welcome to the Sure Send CRM Partner API! This guide will help you get up and running quickly with our API to manage contacts, track events, and integrate with your applications.

Prerequisites

Before you begin, you'll need:

  • A Sure Send CRM account with API access
  • An API token (generated from Settings > API Tokens in your dashboard)
  • Basic knowledge of REST APIs and HTTP requests

Authentication

The Partner API uses Bearer token authentication. Include your API token in the Authorization header of every request:

curl https://api.suresend.ai/api/partner/people \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Quick Start: Create Your First Contact

Let's create a contact in your CRM:

curl -X POST https://api.suresend.ai/api/partner/people \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "emails": [
      {
        "value": "[email protected]",
        "isPrimary": true
      }
    ],
    "phones": [
      {
        "value": "+1-555-1234",
        "type": "mobile",
        "isPrimary": true
      }
    ],
    "tags": ["new-lead"]
  }'

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "firstName": "Jane",
  "lastName": "Doe",
  "name": "Jane Doe",
  "emails": [...],
  "phones": [...],
  "tags": ["new-lead"],
  "createdAt": "2025-10-16T12:00:00Z"
}

Key Concepts

People (Contacts)

People are the core entity in the CRM. They represent your contacts, leads, and customers.

Common Operations:

  • GET /api/partner/people - List all contacts
  • GET /api/partner/people/{id} - Get a specific contact
  • POST /api/partner/people - Create a new contact
  • PUT /api/partner/people/{id} - Update a contact
  • DELETE /api/partner/people/{id} - Delete a contact

Events

Events track all interactions and activities with your contacts (page views, property views, form submissions, etc.).

Example: Track a page view

curl -X POST https://api.suresend.ai/api/partner/events \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "page_view",
    "personId": "123e4567-e89b-12d3-a456-426614174000",
    "pageUrl": "https://example.com/properties/123",
    "pageTitle": "Beautiful 3BR Home"
  }'

Notes & Tasks

Keep detailed records and create follow-ups:

Add a note:

curl -X POST https://api.suresend.ai/api/partner/notes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "123e4567-e89b-12d3-a456-426614174000",
    "subject": "Follow-up call",
    "body": "Discussed property requirements and budget."
  }'

Create a task:

curl -X POST https://api.suresend.ai/api/partner/tasks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Follow up on property inquiry",
    "type": "call",
    "dueDateTime": "2025-10-20T14:00:00Z"
  }'

Rate Limiting

The API implements flexible rate limiting to ensure fair usage:

  • Rate limits are applied per API token
  • Limits can be configured at different levels (global, endpoint, HTTP method)
  • Every response includes rate limit headers:
    • X-RateLimit-Limit - Maximum requests allowed
    • X-RateLimit-Remaining - Requests remaining
    • X-RateLimit-Reset - Window duration in seconds
    • X-RateLimit-Context - Which limit was applied

Example rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 3600
X-RateLimit-Context: token:POST.events

When you exceed a rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header.

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your CRM.

Set up a webhook:

curl -X POST https://api.suresend.ai/api/partner/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Sync Webhook",
    "url": "https://your-app.com/webhooks/crm-events",
    "events": ["peopleCreated", "peopleUpdated", "peopleStageUpdated"]
  }'

Important: The response includes a secretKey which is only shown once. Store it securely - you'll need it to verify webhook signatures.

Verify webhook signatures:

require 'openssl'
require 'rack/utils'

def verify_webhook(request, secret_key)
  received_signature = request.headers['X-Webhook-Signature']
  body = request.body.read

  computed_signature = OpenSSL::HMAC.hexdigest('SHA256', secret_key, body)

  Rack::Utils.secure_compare(computed_signature, received_signature)
end

Error Handling

The API uses standard HTTP status codes:

  • 200 - Success
  • 201 - Created
  • 204 - No Content (successful deletion)
  • 400 - Bad Request
  • 401 - Unauthorized (invalid or missing API token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 422 - Validation Error
  • 429 - Too Many Requests (rate limit exceeded)

Error response format:

{
  "error": "Validation failed",
  "errors": [
    "First name can't be blank",
    "Email is invalid"
  ]
}

Pagination

List endpoints support pagination using page and limit parameters:

curl "https://api.suresend.ai/api/partner/people?page=2&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response includes pagination metadata:

{
  "people": [...],
  "meta": {
    "total_count": 250,
    "current_page": 2,
    "total_pages": 5,
    "per_page": 50
  }
}

Best Practices

  1. Always verify webhook signatures - Never process webhooks without signature verification
  2. Handle rate limits gracefully - Respect Retry-After headers and implement exponential backoff
  3. Use HTTPS - All API requests must use HTTPS
  4. Store API tokens securely - Never expose tokens in client-side code or version control
  5. Use pagination - Don't fetch large datasets in a single request
  6. Implement idempotency - Use event IDs to detect and ignore duplicate webhook deliveries
  7. Monitor rate limit headers - Track your usage to avoid hitting limits

Next Steps

Now that you're familiar with the basics:

  1. Explore the People API to manage contacts
  2. Learn about Events tracking for engagement data
  3. Set up Webhooks for real-time integrations
  4. Check out Custom Fields to extend contact data

Need Help?

  • API Reference: Full endpoint documentation in the sidebar
  • Support: [email protected]
  • Community: Join our developer community (coming soon)

Happy building! 🚀

Updated 8 days ago