Skip to main content

API Integration Guide

This guide provides comprehensive information for integrating with the SBM CRM Platform APIs.

Base URL​

All API requests should be made to:

https://api.sbmcrm.example.com/v1

API Versioning​

The API uses URL versioning. The current version is v1. Future versions will be available at /v2, /v3, etc.

Request Format​

Headers​

All requests must include:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

Request Body​

For POST, PUT, and PATCH requests, send JSON in the request body:

{
  "field1": "value1",
  "field2": "value2"
}

Response Format​

Success Response​

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": "12345",
    "name": "John Doe"
  }
}

Error Response​

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is invalid",
    "details": [
      {
        "field": "email",
        "message": "Email is required"
      }
    ]
  }
}

Common HTTP Status Codes​

  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Rate Limiting​

API requests are rate-limited to ensure fair usage:

  • Standard Tier: 1,000 requests per hour
  • Premium Tier: 10,000 requests per hour
  • Enterprise Tier: Custom limits

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Handling Rate Limits​

When rate limited, you'll receive a 429 status code:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 60 seconds."
  }
}

Pagination​

List endpoints support pagination:

Query Parameters​

  • page - Page number (default: 1)
  • limit - Items per page (default: 20, max: 100)
  • sort - Sort field and direction (e.g., created_at:desc)

Response Format​

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Example Request​

GET /api/v1/customers?page=1&limit=20&sort=created_at:desc

Filtering & Search​

Many endpoints support filtering and search:

Query Parameters​

  • filter[field] - Filter by field value
  • search - Full-text search
  • date_from / date_to - Date range filtering

Example​

GET /api/v1/customers?filter[tier]=gold&filter[status]=active&date_from=2024-01-01

Webhooks​

Webhooks allow you to receive real-time notifications of events. See the Webhooks Guide for details.

Code Examples​

Create Customer​

const response = await fetch('https://api.sbmcrm.example.com/v1/customers', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+1234567890',
    tier: 'bronze'
  })
});

const customer = await response.json();

Get Customer​

const response = await fetch('https://api.sbmcrm.example.com/v1/customers/12345', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const customer = await response.json();

Update Customer​

const response = await fetch('https://api.sbmcrm.example.com/v1/customers/12345', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tier: 'gold'
  })
});

const updatedCustomer = await response.json();

List Customers with Pagination​

const page = 1;
const limit = 20;

const response = await fetch(
  `https://api.sbmcrm.example.com/v1/customers?page=${page}&limit=${limit}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

const result = await response.json();
const customers = result.data;
const pagination = result.pagination;

Award Points​

const response = await fetch('https://api.sbmcrm.example.com/v1/customers/12345/points/award', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    points: 100,
    reason: 'Purchase bonus',
    transaction_id: 'txn_12345'
  })
});

const result = await response.json();

Create Campaign​

const response = await fetch('https://api.sbmcrm.example.com/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Summer Sale 2024',
    description: 'Special summer promotion',
    start_date: '2024-06-01T00:00:00Z',
    end_date: '2024-08-31T23:59:59Z',
    target_segment: 'gold_members',
    reward_type: 'discount',
    reward_value: 20
  })
});

const campaign = await response.json();

Error Handling​

Retry Logic​

Implement exponential backoff for retries:

async function apiRequest(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
        await sleep(retryAfter * 1000);
        continue;
      }
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }
      
      return await response.json();
    } catch (error) {
      if (i === retries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000); // Exponential backoff
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

Error Handling Example​

try {
  const customer = await getCustomer('12345');
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 401:
        // Re-authenticate
        await refreshToken();
        break;
      case 404:
        // Customer not found
        console.log('Customer does not exist');
        break;
      case 429:
        // Rate limited - retry after delay
        await sleep(error.response.headers['retry-after'] * 1000);
        break;
      default:
        console.error('API Error:', error.response.data);
    }
  }
}

SDKs and Libraries​

Official SDKs are available for:

  • JavaScript/Node.js - @sbmcrm/sdk-js
  • Python - sbmcrm-python
  • PHP - sbmcrm-php

Using the JavaScript SDK​

import { SBMCRMClient } from '@sbmcrm/sdk-js';

const client = new SBMCRMClient({
  apiKey: process.env.API_KEY,
  baseURL: 'https://api.sbmcrm.example.com/v1'
});

// Use the client
const customer = await client.customers.get('12345');
const points = await client.customers.awardPoints('12345', {
  points: 100,
  reason: 'Purchase bonus'
});

Testing​

Sandbox Environment​

Use the sandbox environment for testing:

https://api-sandbox.sbmcrm.example.com/v1

Test Credentials​

Test API keys are available in the Admin Web App under Settings → API Keys → Test Keys.

Best Practices​

  1. Always use HTTPS - Never make API calls over HTTP
  2. Store credentials securely - Use environment variables or secure vaults
  3. Implement retry logic - Handle transient failures gracefully
  4. Respect rate limits - Implement rate limiting on your side
  5. Use webhooks - Prefer webhooks over polling for real-time updates
  6. Cache when appropriate - Cache static or infrequently changing data
  7. Handle errors gracefully - Provide meaningful error messages to users
  8. Log API calls - Log requests and responses for debugging (excluding sensitive data)