Universal CRM Partner API for integrating with Sure Send CRM. This API allows partners to manage contacts, activities, and more programmatically. ## Webhook Security When you create a webhook, you receive a secret key that is used to sign all webhook deliveries. **The secret key is only shown once during webhook creation** - store it securely. ### Validating Webhook Signatures Every webhook delivery includes an `X-Webhook-Signature` header containing an HMAC-SHA256 signature of the request body. You **must verify this signature** to ensure the webhook is from Sure Send CRM and hasn't been tampered with. **The header format is `sha256=`.** The `sha256=` prefix is part of the header value, so you must strip it before comparing — every example below does. ``` X-Webhook-Signature: sha256=8f2c1b9e...4d7a ``` **Signature Verification Steps:** 1. Read the `X-Webhook-Signature` header and strip the leading `sha256=` 2. Compute HMAC-SHA256 of the **raw request body** using your secret key 3. Compare the two with a constant-time comparison Sign the raw body exactly as received. Re-serialising the parsed JSON will change key order or spacing and the signature will not match. **Implementation Examples:** **Ruby:** ```ruby require 'openssl' require 'rack/utils' def verify_webhook(request, secret_key) # The header is "sha256=" — strip the prefix before comparing. # delete_prefix, not a regex: this text is published through a Ruby # heredoc, and a `\A` anchor loses its backslash on the way out. received_signature = request.headers['X-Webhook-Signature'].to_s.delete_prefix('sha256=') body = request.body.read computed_signature = OpenSSL::HMAC.hexdigest('SHA256', secret_key, body) # Use constant-time comparison to prevent timing attacks Rack::Utils.secure_compare(computed_signature, received_signature) end ``` **Node.js:** ```javascript const crypto = require('crypto'); function verifyWebhook(req, secretKey) { // The header is "sha256=" — strip the prefix before comparing. const header = req.headers['x-webhook-signature'] || ''; const receivedSignature = header.replace(/^sha256=/, ''); // Sign the RAW body. Use express.raw({type: 'application/json'}) — // JSON.stringify(req.body) re-serialises and the digest will differ. const body = req.rawBody; const computedSignature = crypto .createHmac('sha256', secretKey) .update(body) .digest('hex'); // timingSafeEqual throws on length mismatch, so check that first. const a = Buffer.from(receivedSignature, 'hex'); const b = Buffer.from(computedSignature, 'hex'); return a.length === b.length && crypto.timingSafeEqual(a, b); } ``` **Python:** ```python import hmac import hashlib def verify_webhook(request, secret_key): # The header is "sha256=" — strip the prefix before comparing. header = request.headers.get('X-Webhook-Signature', '') received_signature = header.replace('sha256=', '', 1) body = request.body # raw bytes, not the parsed JSON computed_signature = hmac.new( secret_key.encode('utf-8'), body, hashlib.sha256 ).hexdigest() # Use compare_digest to prevent timing attacks return hmac.compare_digest(computed_signature, received_signature) ``` **PHP:** ```php function verifyWebhook($request, $secretKey) { // The header is "sha256=" — strip the prefix before comparing. $header = $request->header('X-Webhook-Signature') ?? ''; $receivedSignature = str_replace('sha256=', '', $header); $body = $request->getContent(); // raw body, not re-encoded JSON $computedSignature = hash_hmac('sha256', $body, $secretKey); // Use hash_equals to prevent timing attacks return hash_equals($computedSignature, $receivedSignature); } ``` ### Security Best Practices 1. **Always Verify Signatures**: Never process webhooks without verifying the signature 2. **Use Constant-Time Comparison**: Prevents timing attacks (use `secure_compare`, `timingSafeEqual`, `compare_digest`, or `hash_equals`) 3. **Store Secret Keys Securely**: Use environment variables or secret management services 4. **Use HTTPS Only**: Webhook URLs must use HTTPS to encrypt data in transit 5. **Validate Payload Structure**: Check that the payload matches expected schema before processing 6. **Implement Idempotency**: Use the `eventId` to detect and ignore duplicate deliveries 7. **Rate Limit Webhook Endpoints**: Protect your endpoint from abuse 8. **Log Failed Verifications**: Monitor for potential security issues ### Webhook Delivery Format All webhooks are delivered as POST requests with: - **Content-Type**: `application/json` - **X-Webhook-Signature**: `sha256=` HMAC-SHA256 signature of the raw body - **Suresendcrm-Signature**: the same value as `X-Webhook-Signature` - **X-Event-Id**: the payload's `eventId` - **X-System**: the webhook's system identifier (`partner_api` by default) - **User-Agent**: `SureSendCRM-Webhooks/1.0` Deliveries are sent about 3 seconds after the change. Object keys in the body are sorted; always verify the signature against the raw bytes. Example payload: ```json { "eventId": "550e8400-e29b-41d4-a716-446655440000", "eventCreated": "2025-10-16T12:00:00Z", "event": "peopleCreated", "resourceIds": ["123e4567-e89b-12d3-a456-426614174000"], "uri": "https://api.suresend.ai/api/partner/people/123e4567-e89b-12d3-a456-426614174000", "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "firstName": "John", "lastName": "Doe", "email": "john@example.com", "registrationPropertyActivity": { "eventId": "9c1f...", "eventType": "Registration", "occurredAt": "2025-10-16T11:58:00Z", "propertyData": { "mlsNumber": "224108234", "address": "123 Main St, Sacramento, CA 95814", "price": 750000, "bedrooms": 4, "bathrooms": 2.5, "area": 2400, "url": "https://ezhomesearch.com/listing/123", "imageUrl": "https://cdn.example.com/listing-image.jpg" } } } } ``` ### Relationship Events: Key Off `relationship_type_id`, Not the Name Relationship webhooks (`peopleRelationshipsCreated`, `peopleRelationshipsUpdated`, `peopleRelationshipsDeleted`) carry the relationship type three ways. Note these `data` keys are snake_case, unlike the contact example above: ```json { "event": "peopleRelationshipsUpdated", "data": { "person_id": "123e4567-e89b-12d3-a456-426614174000", "related_person_id": "9c1f8400-e29b-41d4-a716-446655440111", "relationship_type": "Referral Agent", "relationship_type_id": "8f14e45f-ceea-467a-9ed5-6a1c0e1d2f34", "relationship_type_name": "Referral Agent" } } ``` **Match on `relationship_type_id`.** Teams can define their own relationship types in addition to the eight built-in ones, and can rename the types they defined: - Renaming a custom type is reflected in the very next event. An integration matching on the string `"Referral Agent"` silently stops matching when that team renames it to `"Referral Partner"` — no error, no failed delivery. - Custom type names are unique per account, not globally. Two accounts can each have a `"Referral Agent"` meaning different things, with different ids. The eight built-in types (`Spouse`, `Child`, `Parent`, `Sibling`, `Relative`, `Business Partner`, `Friend`, `Other`) **cannot be renamed or deleted**, so matching those names remains reliable. `relationship_type_id` is stable across renames and unambiguous across accounts, which is why it is the field to match on. `relationship_type` stays in the payload unchanged and is not being removed — it is kept for readability and for backward compatibility with existing integrations. ### Handling Webhook Failures - Your endpoint must accept the connection within 5 seconds and respond within 10 seconds. A `2xx` status acknowledges the delivery - `406` or `410` sets the webhook to `disabled` immediately, with no retries - Any other `4xx` fails the delivery without retrying it - `5xx`, other non-2xx statuses (redirects are not followed), timeouts and connection errors are retried. A delivery gets up to 6 attempts: the first plus retries about 1 s, 16 s, 81 s, 256 s and 625 s after each failure (roughly 16 minutes in total) - Each webhook keeps a failure counter (`retry_count`). An attempt that gets a `5xx` (or other retryable status) adds 1, a timeout or connection error adds nothing, and a delivery that uses up all 6 attempts adds 1 more. Any successful delivery resets it to 0. When a delivery uses up its attempts with the counter at 10 or more, the webhook's status becomes `failed` and deliveries stop — about two deliveries in a row that keep returning `5xx`, or about ten in a row that time out - No email or in-app notification is sent when a webhook becomes `disabled` or `failed`. Monitor the webhook's `status` - Re-enabling a webhook (`PUT /webhooks/{id}` with `status: active`) does not reset the counter; a successful delivery does, so send a test delivery after re-enabling - Every delivery is logged for 7 days. `GET /webhooks/{id}/deliveries` lists the last 3 days, `GET /webhook_deliveries/{id}` fetches one, `POST /webhook_deliveries/{id}/retry` re-sends a failed delivery and `POST /webhook_deliveries/{id}/replay` re-sends a completed one (including a successful one). Retried and replayed deliveries keep the same `eventId` - You can test your webhook endpoint using the `/webhooks/{id}/test` endpoint ## Lender Webhook Reference Every loan event you can subscribe to. All are delivered in the standard envelope above; the `data` object is documented here. **Scoping applies to pushes too.** A USER-scoped subscription receives only loans that user can see — an officer's own book. A TEAM-scoped subscription receives everything on the team. There is no way to subscribe to another officer's loans. | Event | Fires when | | -- | -- | | `loansCreated` | A loan file is opened | | `loansUpdated` | Any loan field changes (not the stage) | | `loansStageUpdated` | A loan moves between stages | | `loansFunded` | A loan reaches the funded stage | | `loansClearToClose` | A loan reaches clear-to-close | | `loansArchived` | A loan is lost, withdrawn, denied or expired | | `loansDeleted` | A loan created in error is permanently deleted. Unlike an archive, nothing is left to read back — delete your copy | | `loansLockExpiring` | A rate lock crosses the 10-day and 5-day thresholds | | `loansAppraisalUpdated` | Appraisal status changes | | `loansUnderwritingUpdated` | Underwriting status changes | | `loansPurchased` | A funded loan is sold to a servicer (FIRST write only) | ### The `data` object on every loans* event ```json { "loanId": "018f...", "contactId": "018f...", "stage": "underwriting", "purpose": "purchase", "loanType": "conventional", "amount": "425000.0", "assignedToUserId": "018f...", "referralPartnerId": "018f...", "source": "api", "sourceIntegration": "Encompass", "occurredAt": "2026-08-17T14:22:31Z" } ``` `stage` and `loanType` are **stable keys**, never display names — teams rename stages routinely and a subscriber branching on a label would break the first time they did. ### Events that carry extra fields * `loansStageUpdated` adds `fromStage` and `toStage`, both keys. * `loansLockExpiring` adds `thresholdDays` (`10` or `5`). A loan notifies at most once per threshold, and crossing into the tighter one notifies again — so a lock inside 5 days does not re-notify daily. * `loansPurchased` adds `servicer` with its company name and loan number. ### One move, several events A single stage transition can publish up to three events: always `loansStageUpdated`, plus `loansFunded` when the destination is the funded stage, plus `loansClearToClose` when it is clear-to-close. This is deliberate — a subscriber that only cares about funding should not have to inspect every move to find it. All three carry the same `eventId` family and are individually retried. ## Idempotency All write operations (`POST`, `PUT`, `PATCH`) on the Partner API are **automatically idempotent within a 30-second window**. If your client retries the exact same request (same method, path, and JSON body) within 30 seconds, the API replays the original response instead of executing the action a second time. This prevents accidental duplicate records when a network timeout or transient error causes a retry of a request that actually succeeded. ### How It Works 1. The API fingerprints each write request by hashing `api_token + method + path + sorted JSON body`. 2. If an identical fingerprint arrives within 30 seconds of the original, the cached response body, status code, and `Content-Type` are replayed. 3. Replayed responses include the header `X-Idempotent-Replay: true` so your client can distinguish a fresh execution from a replay. ### Failure Semantics (Important) - **Only 2xx responses are replayed.** If the original request returned 4xx or 5xx, the dedup window is cleared and your retry will be **re-executed** (not replayed). This lets you fix a bad payload and retry immediately. - **If a duplicate has no cached response**, the API returns `409 Conflict` with an `errorMessage` and `Retry-After: 30`. The original may still be processing, or its response may be unavailable. This does not confirm success or failure of the original write. Fetch the resource to verify its state before retrying after the delay. - **If the original response body exceeds 64 KB**, it is not cached; duplicates return the same `409 Conflict`. Duplicate `DELETE` requests also return `409` because DELETE responses are not cached. ### DX Hazard: Nonces in Payloads The fingerprint is computed from the request body. If you include a changing value in every retry (e.g., a client-side timestamp or UUID), retries will hash differently and the dedup guard will be bypassed silently. Keep retried payloads byte-identical to benefit from idempotent-replay. ### Example ```http POST /api/partner/people Authorization: Bearer Content-Type: application/json { "firstName": "Ada", "lastName": "Lovelace" } ``` First response: `201 Created` with the full person object (including `id`). Retry within 30s with the same body: `201 Created`, identical body, and `X-Idempotent-Replay: true`. ## Rate Limiting The Partner API implements a flexible, context-aware rate limiting system to ensure fair usage and API stability. ### How Rate Limits Work ### Default Limits | Scenario | Limit | |----------|-------| | No `X-System-Id` header | 300 requests/minute | | A registered, active System ID in `X-System-Id` | 600 requests/minute | Default limits are counted **per team, not per API token**: every API token on a team shares the same allowance, so creating more tokens does not add capacity. Each resource (for example `/people`, `/tasks`, `/calls`) has its own counter, and requests with a System ID are counted separately for each System ID. The window is a fixed 60 seconds starting with the first request counted in it. ### Custom Limits Sure Send staff can configure a custom limit that replaces the default. It can be set on: - **A team**: applies to every API token in the team - **A System ID**: applies to requests that send that `X-System-Id` - **An API token**: applies to that token only, and takes precedence over the other two To ask for a higher limit, register a System ID first (600 requests/minute), then email help@suresend.ai with your team name, System ID, the endpoints you call and the rate you need. ### Rate Limit Contexts Rate limits are applied based on context, from most specific to least specific: 1. **HTTP Method + Endpoint**: `POST.events`, `PUT.people`, `GET.events` 2. **Endpoint**: `events`, `people`, `notes`, `tasks` 3. **Global**: All API requests When a request is made, the system checks for the most specific rate limit configuration first. If a more specific limit exists, it takes precedence over broader limits. **Example**: If you have: - `POST.events`: 100 requests/hour - `events`: 500 requests/hour - `global`: 1000 requests/hour POST requests to `/api/partner/events` will be limited to 100/hour, while GET requests will use the 500/hour limit. ### Rate Limit Headers Every API response includes rate limit information in the headers: ``` X-RateLimit-Limit: 100 # Maximum requests allowed X-RateLimit-Remaining: 85 # Requests remaining in window X-RateLimit-Reset: 3600 # Window duration in seconds X-RateLimit-Context: api_token:POST.events # Which limit was applied ``` When you exceed a rate limit, you'll receive a `429 Too Many Requests` response with: ``` Retry-After: 3600 # Seconds until window resets X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 3600 X-RateLimit-Context: api_token:POST.events X-Throttle-Reason: rate_limit # "circuit_breaker" when the 429 is not a rate limit — see below ``` ### Reading `X-RateLimit-Context` The value identifies which bucket was applied, so you can tell a configured limit apart from a default one when handling a 429: | Value | Meaning | |-------|---------| | `api_token:` | A rate limit configured on your API token | | `api_system:` | A rate limit configured on your registered System ID | | `team:` | A rate limit configured at the team level | | `token:default` | The default team limit, 300/minute (no System ID) | | `api_system:default` | The default limit for a valid `X-System-Id`, 600/minute | | `token:custom` | A custom per-token limit set by an administrator | ### Rate Limit Response When rate limited, the API returns: ```json { "error": "Rate limit exceeded", "message": "Too many requests for context 'POST.events'. Please retry after 3600 seconds.", "context": "POST.events", "limit": 100, "window_seconds": 3600, "retry_after": 3600 } ``` ### Circuit breaker (not a rate limit) Separately from rate limits, each API token has a circuit breaker. After 20 consecutive failed requests it pauses the token for 5 minutes and answers every request in that window with `429 Too Many Requests`. These responses carry no `X-RateLimit-*` headers and are identifiable on their own: ``` Retry-After: 300 X-Throttle-Reason: circuit_breaker ``` ```json { "errorMessage": "Circuit breaker open: 20 consecutive requests on this API token failed (most recent: POST /api/partner/notes returned 400). This is not a rate limit. All requests on this token are paused for 300 seconds; fix the failing calls before retrying.", "code": "circuit_breaker_open", "retryAfter": 300, "lastFailure": { "method": "POST", "path": "/api/partner/notes", "status": 400 } } ``` What counts toward the breaker: - Any `2xx` response clears the run of failures. - `402`, `404`, and `429` are ignored — being out of AI credits, a lookup that misses, and a throttle say nothing about your integration's health. - Every other non-`2xx` response (`400`, `403`, `422`, `5xx`) counts as one failure. - Requests rejected before they reach the endpoint are not counted at all: a `401` from a missing, invalid or expired token, and a `402` from an inactive subscription. The breaker measures calls your token actually made, not calls it was not allowed to make. If you receive `X-Throttle-Reason: circuit_breaker`, raising your rate limit will not help: fix the call named in `lastFailure`, then wait out `Retry-After`. ### Best Practices 1. **Monitor Headers**: Check `X-RateLimit-Remaining` to track your usage 2. **Implement Backoff**: When you receive a 429, wait for the duration specified in `Retry-After` 3. **Batch Requests**: Use query parameters to fetch multiple records when possible 4. **Spread Load**: Distribute high-volume operations over time 5. **Contact Support**: Need higher limits? Contact us to discuss your use case ### Available Contexts - `global` - All API requests - `events` - All events endpoints - `POST.events` - Create events only - `GET.events` - List/get events only - `people` - All people endpoints - `PUT.people` - Update people only - `notes` - All notes endpoints - `tasks` - All tasks endpoints - `companies` - All companies endpoints - `stages` - All stages endpoints - `appointments` - All appointments endpoints - `calls` - All calls endpoints - `text_messages` - All text messages endpoints - `email_messages` - All email messages endpoints