Skip to main content

​
Installation

Install via pip: 
pip install cms-python

​
Requirements

  • Python 3.8 or higher
  • requests library (installed as dependency)

​
Quick Start

#!/usr/bin/env python3
from cms_python import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

​
Non-Deferred Lead Tracking

Track lead events with complete information including the click_id. 
#!/usr/bin/env python3
from cms_python import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Standard lead with complete payload
response = client.track_lead(
    click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
    event_name="signup_started",
    customer_external_id="user_42",
    customer_name="John Doe",
    customer_email="john@example.com",
)

print(response)

​
Lead Tracking Parameters

  • click_id (str) - The unique click identifier
  • event_name (str) - Name of the lead event (e.g., “signup_started”, “email_verified”)
  • customer_external_id (str) - Your internal customer identifier
  • customer_name (str, optional) - Full name of the customer
  • customer_email (str, optional) - Customer’s email address
  • customer_avatar (str, optional) - URL to customer’s avatar/profile picture
  • timestamp (str, optional) - ISO 8601 timestamp (auto-set if not provided)

​
Deferred Lead Tracking

Use deferred mode for two-step lead attribution when the click_id isn’t available at the event time.

​
Step 1: Initialize Deferred Lead Tracking

#!/usr/bin/env python3
from cms_python import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Step 1: Setup deferred mode - store clickId association
response = client.track_lead(
    click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
    event_name="lead_captured",
    customer_external_id="user_72",
    customer_name="Jane Smith",
    customer_email="jane@example.com",
    mode="deferred",
)

print(response)

​
Step 2: Track Follow-up Events

#!/usr/bin/env python3
from cms_python import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Step 2: Later, track using just customer_external_id (no click_id)
response = client.track_lead(
    event_name="kyc_completed",
    customer_external_id="user_72",
)

print(response)
Key Benefits:
  • Store click context for later reference
  • Track multiple user journey events without losing attribution
  • Simplify event tracking for complex workflows
Complete Deferred Example: 
#!/usr/bin/env python3
from cms_python import CMSClient

bearer_token = "your_bearer_token"
client = CMSClient(token=bearer_token)

# Initialize deferred tracking
client.track_lead(
    click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
    event_name="signup_started",
    customer_external_id="user_42",
    customer_name="cutmeshort",
    customer_email="cutmeshort@cms.com",
    mode="deferred",
)

# Track email verification without click_id
client.track_lead(
    event_name="email_verified",
    customer_external_id="user_42",
)

# Track account creation without click_id
client.track_lead(
    event_name="account_created",
    customer_external_id="user_42",
)

​
Sale Tracking

Track completed sales and revenue events with full transaction details. 
#!/usr/bin/env python3
import os
from cms_python import CMSClient

# Get Bearer token from environment
bearer_token = os.environ.get("CMS_BEARER_TOKEN", "your_bearer_token")

# Create client
client = CMSClient(token=bearer_token)

# Track a sale
response = client.track_sale(
    click_id="id_123",
    event_name="purchase_completed",
    customer_external_id="user_42",
    invoice_id="inv_987",
    amount=4999,  # amount in cents ($49.99)
    currency="USD",
    customer_name="John Doe",
    customer_email="john@example.com",
)

print(response)

​
Sale Tracking Parameters

  • click_id (str) - The unique click identifier
  • event_name (str) - Name of the sale event (e.g., “purchase_completed”, “payment_received”)
  • customer_external_id (str) - Your internal customer identifier
  • invoice_id (str) - Invoice or transaction identifier
  • amount (int) - Amount in cents (e.g., 4999 = $49.99)
  • currency (str) - 3-letter currency code (e.g., “USD”, “EUR”, “INR”)
  • customer_name (str, optional) - Customer’s name
  • customer_email (str, optional) - Customer’s email
  • customer_avatar (str, optional) - URL to customer’s avatar
  • timestamp (str, optional) - ISO 8601 timestamp (auto-set if not provided)

​
Error Handling

#!/usr/bin/env python3
from cms_python import CMSClient

client = CMSClient(token="your_bearer_token")

try:
    response = client.track_lead(
        click_id="5e6e1650-5641-4a2b-bec6-218288a86dbf",
        event_name="signup_started",
        customer_external_id="user_42",
    )
    
    if response.success:
        print("✅ Lead tracking successful!")
    else:
        print(f"❌ Error: {response.error}")
        
except Exception as e:
    print(f"Exception: {str(e)}")

​
Documentation

For complete documentation, visit Python SDK Docs