Additional Information

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests.

Common Error Codes

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request parameters are invalid",
    "details": [
      {
        "field": "leadId",
        "message": "leadId must be a valid UUID"
      }
    ]
  }
}

Pagination

List endpoints support pagination using cursor-based navigation.

Query Parameters

Response Format

{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJsYXN0SWQiOiIxMjM0In0=",
    "hasMore": true
  }
}

Webhook Security

Webhook payloads are signed using HMAC-SHA256. Verify signatures to ensure authenticity.

Signature Verification

1. Extract the X-Signature header from the webhook request
2. Compute HMAC-SHA256 of the request body using your webhook secret
3. Compare the computed signature with the header value

Example (Node.js)

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}

Data Retention

• Leads data: Retained for 24 months from creation date
• Webhook delivery logs: Retained for 30 days
• Audit logs: Retained for 12 months

Changelog

Version 1.4.0 (Current)

• Added webhook subscription management endpoints
• Added webhook delivery audit endpoint
• Improved error response format

Version 1.3.0

• Added pagination support for leads listing
• Added filtering by date range

Version 1.2.0

• Added AGENCY and PROPERTY_SEARCH lead categories
• Added lead source tracking

Version 1.1.0

• Initial public release
• Basic lead retrieval endpoints