SuperBook CRM API Documentation 🔗

Setup 🔗

Add these constants to your wp-config.php file:

define('ODB_CRM_API_KEY', 'your_api_key_here');
define('ODB_CRM_API_SECRET', 'your_api_secret_here');

Authentication 🔗

All API requests require authentication via headers or query parameters:

Headers (Recommended):

X-API-Key: your_api_key_here
X-API-Secret: your_api_secret_here

Query Parameters (Alternative):

?api_key=your_api_key_here&api_secret=your_api_secret_here

Base URL 🔗

https://yourdomain.com/wp-json/crm/v2/

Important Notes 🔗

API only works with subscriber role users (clients)
All requests must include valid API credentials
All dates use format: YYYY-MM-DD HH:MM:SS
All responses return JSON

---

Endpoints 🔗

1. Get Single User 🔗

GET /user

Get a single user by ID, login, email, or current user.

Parameters:

id (integer) - User ID
login (string) - Username
email (string) - Email address
target (string) - Use me for current authenticated user
fields (string) - Comma-separated list of fields to return (optional)

Example:

curl -X GET "https://yourdomain.com/wp-json/crm/v2/user?id=6" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

Response:

{
  "ID": "6",
  "user_login": "client_abc123_6",
  "user_email": "[email protected]",
  "display_name": "John Doe",
  "roles": ["subscriber"],
  "first_name": "John",
  "last_name": "Doe",
  "meta:phone": "050-1234567",
  "meta:whatsapp_username": "johndoe2026",
  "meta:additional_phone": "052-9876543",
  "meta:address": "123 Main St",
  "meta:city": "Tel Aviv",
  "meta:follow_up_datetime": "2026-02-15 14:30:00",
  "meta:client_group": {
    "id": "group2",
    "name": "Group 2"
  },
  "meta:user_tags": [
    {
      "id": "tag1",
      "name": "Tag 1"
    }
  ],
  "meta:notes_timeline": [
    {
      "content": "Meeting scheduled",
      "timestamp": "2026-02-10 09:23:52",
      "author": 0,
      "author_name": false
    }
  ],
  "meta:archived": false,
  "meta:hidden": false,
  "meta:consent_given": true,
  "meta:consent_timestamp": "2026-02-19 10:30:00",
  "meta:newsletter_signup": false
}

---

2. List Users 🔗

GET /users

Get a list of users with filtering and pagination.

Parameters:

search (string) - Search by name, email, or username
page (integer) - Page number (default: 1)
per_page (integer) - Results per page (default: 10)
orderby (string) - Sort field (default: display_name)
order (string) - Sort order: ASC or DESC (default: ASC)
follow_up (string) - Filter by follow-up date: today, overdue, future
archived (boolean) - Filter by archived status
hidden (boolean) - Filter by hidden status
client_group (string) - Filter by group: group1, group2, group3, group4
consent_given (boolean) - Filter by consent status
newsletter_signup (boolean) - Filter by newsletter subscription status

Example:

curl -X GET "https://yourdomain.com/wp-json/crm/v2/users?per_page=5&follow_up=today" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

Response:

{
  "users": [
    {
      "ID": "5",
      "display_name": "Jane Smith",
      "meta:phone": "050-9876543",
      "meta:follow_up_datetime": "2026-02-10 10:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 5
}

---

3. Create User 🔗

POST /user

Create a new client (subscriber) or update existing if duplicate found.

Duplicate Detection:

Checks email first (exact match)
Then checks phone number (normalized Israeli format)
If duplicate found, updates existing client instead of creating new one

Parameters:

display_name (string, required) - Full name
email (string) - Email (auto-generated if not provided)
phone (string) - Phone number
whatsapp_username (string) - WhatsApp username (without @ symbol)
additional_phone (string) - Secondary/backup phone number
address (string) - Address
city (string) - City
links (array) - Array of link objects: [{"label": "Website", "url": "https://..."}]
follow_up_datetime (string) - Follow-up date: YYYY-MM-DD HH:MM:SS (only used for new clients)
initial_note (string) - Initial note to add to timeline
profile_picture_url (string) - URL to profile picture
client_group (string) - Group: group1, group2, group3, group4, or empty
user_tags (array) - Array of tag IDs: ["tag1", "tag2"]
archived (boolean) - Archive status
hidden (boolean) - Hidden status
follow_up_pinned (boolean) - Pin follow-up to "Today" view
source (string) - Source identifier (e.g., "Elementor Form #123", "AI Agent")
consent_given (boolean) - User consent status (for legal compliance)
newsletter_signup (boolean) - Newsletter subscription preference

Behavior on New Client:

Creates new subscriber user
Sets follow-up to today (or provided date)
Pins follow-up
Adds note with source and message

Behavior on Duplicate (Found by Email):

Updates client fields
If phone is different, adds phone to note
Pins follow-up (keeps existing date)
Adds note with source and message

Behavior on Duplicate (Found by Phone):

Updates client fields
If current email is auto-generated (@currentDomain), replaces with new email
If new email is real and different, adds email to note
Pins follow-up (keeps existing date)
Adds note with source and message

Example (New Client):

curl -X POST "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "John Doe",
    "phone": "050-1234567",
    "whatsapp_username": "johndoe2026",
    "additional_phone": "052-9876543",
    "email": "[email protected]",
    "city": "Tel Aviv",
    "client_group": "group2",
    "source": "Elementor Form #123",
    "initial_note": "Interested in premium package",
    "consent_given": true,
    "newsletter_signup": false
  }'

Response (New Client - 201):

{
  "ID": "7",
  "display_name": "John Doe",
  "user_email": "[email protected]",
  "meta:phone": "050-1234567",
  "meta:whatsapp_username": "johndoe2026",
  "meta:additional_phone": "052-9876543",
  "meta:follow_up_datetime": "2026-02-19 10:30:00",
  "meta:follow_up_pinned": true,
  "meta:client_group": {
    "id": "group2",
    "name": "Group 2"
  },
  "meta:notes_timeline": [
    {
      "content": "Elementor Form #123\nConsent: Yes (19/02/2026 10:30:00)\nNewsletter: No\nInterested in premium package",
      "timestamp": "2026-02-19 10:30:00"
    }
  ],
  "meta:consent_given": true,
  "meta:consent_timestamp": "2026-02-19 10:30:00",
  "meta:newsletter_signup": false
}

Example (Duplicate Found by Email):

curl -X POST "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "John Doe",
    "phone": "052-9999999",
    "email": "[email protected]",
    "source": "Elementor Form #123",
    "initial_note": "Called again with new number",
    "consent_given": false,
    "newsletter_signup": true
  }'

Response (Duplicate - 200):

{
  "ID": "7",
  "display_name": "John Doe",
  "user_email": "[email protected]",
  "meta:phone": "052-9999999",
  "meta:follow_up_datetime": "2026-02-15 14:00:00",
  "meta:follow_up_pinned": true,
  "meta:notes_timeline": [
    {
      "content": "Elementor Form #123\nConsent: No (19/02/2026 10:35:00)\nNewsletter: Yes\nCalled again with new number\nPhone: 052-9999999",
      "timestamp": "2026-02-19 10:35:00"
    },
    {
      "content": "Elementor Form #123\nConsent: Yes (19/02/2026 10:30:00)\nNewsletter: No\nInterested in premium package",
      "timestamp": "2026-02-19 10:30:00"
    }
  ],
  "meta:consent_given": false,
  "meta:consent_timestamp": "2026-02-19 10:30:00",
  "meta:newsletter_signup": true
}

---

4. Update User 🔗

PATCH /user

Update an existing client.

Parameters:

id (integer, required) - User ID
display_name (string) - Full name
email (string) - Email
phone (string) - Phone number
whatsapp_username (string) - WhatsApp username (without @ symbol)
additional_phone (string) - Secondary/backup phone number
address (string) - Address
city (string) - City
links (array) - Array of link objects
follow_up_datetime (string) - Follow-up date: YYYY-MM-DD HH:MM:SS
add_note (string) - Add note to timeline
profile_picture_url (string) - URL to profile picture
client_group (string) - Group: group1, group2, group3, group4, or empty
user_tags (array) - Array of tag IDs: ["tag1", "tag2"]
archived (boolean) - Archive status
hidden (boolean) - Hidden status
follow_up_pinned (boolean) - Pin follow-up to "Today" view
require_confirmation (boolean) - Require email confirmation for email changes
consent_given (boolean) - User consent status (for legal compliance)
newsletter_signup (boolean) - Newsletter subscription preference

Example:

curl -X PATCH "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 6,
    "follow_up_datetime": "2026-02-20 10:00:00",
    "add_note": "Follow-up rescheduled",
    "client_group": "group3",
    "consent_given": true,
    "newsletter_signup": false
  }'

Response:

{
  "ID": "6",
  "display_name": "John Doe",
  "meta:follow_up_datetime": "2026-02-20 10:00:00",
  "meta:client_group": {
    "id": "group3",
    "name": "Group 3"
  },
  "meta:notes_timeline": [
    {
      "content": "Follow-up rescheduled",
      "timestamp": "2026-02-10 10:15:00"
    }
  ]
}

---

5. Delete User 🔗

DELETE /user

Delete a client permanently.

Parameters:

id (integer, required) - User ID

Example:

curl -X DELETE "https://yourdomain.com/wp-json/crm/v2/user?id=6" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

Response:

{
  "deleted": true,
  "id": 6
}

---

6. Toggle User Tag 🔗

PATCH /user/tags

Add or remove a tag from a user.

Parameters:

user_id (integer, required) - User ID
tag_id (string, required) - Tag ID: tag1, tag2, tag3, tag4, tag5
active (boolean, required) - true to add, false to remove

Example:

curl -X PATCH "https://yourdomain.com/wp-json/crm/v2/user/tags" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 6,
    "tag_id": "tag1",
    "active": true
  }'

Response:

{
  "success": true,
  "user_id": 6,
  "tag_id": "tag1",
  "active": true,
  "user_tags": ["tag1"]
}

---

Client Groups 🔗

Available groups (IDs are fixed, names are customizable in admin settings):

group1 - Default: "Group 1"
group2 - Default: "Group 2"
group3 - Default: "Group 3"
group4 - Default: "Group 4"

---

User Tags 🔗

Available tags (IDs are fixed, names are customizable in admin settings):

tag1 - Default: "Tag 1"
tag2 - Default: "Tag 2"
tag3 - Default: "Tag 3"
tag4 - Default: "Tag 4"
tag5 - Default: "Tag 5"

---

SuperBook CRM includes built-in consent and newsletter management for legal compliance, particularly useful for Israeli businesses following local privacy laws.

consent_given (boolean)

User's consent status for data processing
Automatically timestamped when first granted
Required for legal compliance in many jurisdictions

consent_timestamp (string, read-only)

Timestamp when consent was first granted
Format: YYYY-MM-DD HH:MM:SS
Preserved for audit trail (never updated, only set once)

newsletter_signup (boolean)

User's newsletter subscription preference
Independent of consent status
Can be updated anytime

Legal Compliance Features 🔗

Automatic Timestamping:

When consent_given changes from false to true, timestamp is recorded
Timestamp is never overwritten (preserves original consent date)
Provides audit trail for legal requirements

Notes Integration:

Consent and newsletter status automatically added to client notes
Format: "Consent: Yes (22/02/2026 14:30), Newsletter: No"
Includes timestamp for legal documentation

Form Integration 🔗

The API automatically captures consent and newsletter preferences from:

Elementor Pro Forms:

Maps checkbox fields by label keywords
Consent keywords: consent, privacy, agree, gdpr, terms
Newsletter keywords: newsletter, marketing, updates, subscribe, mailing

Contact Form 7:

Configurable field tag mapping in admin settings
Default consent tags: consent, privacy, agree, gdpr, terms
Default newsletter tags: newsletter, marketing, updates, subscribe, mailing

API Examples 🔗

Create client with consent:

curl -X POST "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "John Doe",
    "email": "[email protected]",
    "phone": "050-1234567",
    "source": "Contact Form",
    "initial_note": "Inquiry about services",
    "consent_given": true,
    "newsletter_signup": false
  }'

Update consent status:

curl -X PATCH "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 123,
    "consent_given": false,
    "newsletter_signup": true,
    "add_note": "Updated privacy preferences"
  }'

Query clients by consent status:

curl -X GET "https://yourdomain.com/wp-json/crm/v2/users?consent_given=true&newsletter_signup=false" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

Response Format 🔗

All user responses include consent fields:

{
  "ID": "123",
  "display_name": "John Doe",
  "meta:consent_given": true,
  "meta:consent_timestamp": "2026-02-22 14:30:00",
  "meta:newsletter_signup": false,
  "meta:notes_timeline": [
    {
      "content": "Contact Form\nConsent: Yes (22/02/2026 14:30:00)\nNewsletter: No\nInquiry about services",
      "timestamp": "2026-02-22 14:30:00"
    }
  ]
}

---

WhatsApp Integration (2026 Ready) 🔗

SuperBook CRM is prepared for WhatsApp's 2026 transition from phone numbers to usernames. The API supports both traditional phone-based and modern username-based WhatsApp communication.

WhatsApp Fields 🔗

whatsapp_username (string)

WhatsApp username without the @ symbol
Example: "johndoe2026" (not "@johndoe2026")
Used for WhatsApp Business API integration
Future-ready for WhatsApp's username system

additional_phone (string)

Secondary phone number for backup contact
Can be business phone, family member, or landline
Supports same normalization as primary phone field
Useful for multi-channel communication strategies

WhatsApp API Examples 🔗

Create client with WhatsApp data:

curl -X POST "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Sarah Cohen",
    "phone": "050-1234567",
    "whatsapp_username": "sarahc2026",
    "additional_phone": "03-5551234",
    "email": "[email protected]",
    "source": "WhatsApp Business Integration"
  }'

Update WhatsApp information:

curl -X PATCH "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 15,
    "whatsapp_username": "newusername2026",
    "additional_phone": "052-9999999",
    "add_note": "Updated WhatsApp contact information"
  }'

Migration Strategy 🔗

Current (2024-2026): Use both phone and WhatsApp username

Primary phone for calls/SMS
WhatsApp username for messaging
Additional phone for backup contact

Future (2026+): WhatsApp username becomes primary for messaging

Phone numbers still supported for calls
WhatsApp usernames for all messaging workflows
Seamless transition without data loss

---

Phone Number Normalization 🔗

The API automatically normalizes Israeli phone numbers for duplicate detection:

Supported Formats:

050-123-4567 → 972501234567
972-50-123-4567 → 972501234567
+972501234567 → 972501234567
0501234567 → 972501234567
(050) 123-4567 → 972501234567

How it Works:

Strips all non-digit characters
Converts to standard format: 972XXXXXXXXX
Handles domestic (0...) and international (972...) formats
Requires minimum 9 digits

This ensures duplicate detection works regardless of how users format phone numbers.

---

Error Responses 🔗

401 Unauthorized:

{
  "code": "api_forbidden",
  "message": "Invalid API credentials.",
  "data": {
    "status": 401
  }
}

403 Forbidden:

{
  "code": "invalid_role",
  "message": "API only works with subscriber role.",
  "data": {
    "status": 403
  }
}

404 Not Found:

{
  "code": "user_not_found",
  "message": "User not found.",
  "data": {
    "status": 404
  }
}

500 Server Error:

{
  "code": "api_not_configured",
  "message": "API authentication not configured.",
  "data": {
    "status": 500
  }
}

---

Webhooks 🔗

SuperBook CRM sends webhooks for client events to external systems (Zapier, Make.com, custom endpoints).

Webhook Events 🔗

client_created - New client created
client_updated - Client information updated
note_added - Note added to client timeline
follow_up_changed - Follow-up date/time changed

Webhook Payload Structure 🔗

All webhooks include the complete client data with consent, newsletter, and WhatsApp fields:

{
  "event": "client_created",
  "timestamp": "2026-02-22 15:30:00",
  "site_url": "https://yourdomain.com",
  "user_id": 123,
  "user": {
    "ID": 123,
    "display_name": "John Doe",
    "email": "[email protected]",
    "phone": "050-1234567",
    "whatsapp_username": "johndoe2026",
    "additional_phone": "052-9876543",
    "city": "Tel Aviv",
    "client_group": "group1",
    "user_tags": ["tag1"],
    "follow_up_datetime": "2026-02-25 10:00:00",
    "archived": false,
    "hidden": false,
    "consent_given": true,
    "consent_timestamp": "2026-02-22 15:30:00",
    "newsletter_signup": false
  }
}

Event-Specific Data 🔗

note_added includes changes object:

{
  "event": "note_added",
  "changes": {
    "note": {
      "content": "Client called for support",
      "author": "Admin User",
      "timestamp": "2026-02-22 15:30:00"
    }
  }
}

follow_up_changed includes old/new values:

{
  "event": "follow_up_changed", 
  "changes": {
    "follow_up_datetime": {
      "old": "2026-02-20 10:00:00",
      "new": "2026-02-25 14:30:00"
    }
  }
}

Webhook Configuration 🔗

Webhooks are configured in the CRM admin panel. Each webhook can subscribe to specific events and will receive the full client data plus event-specific changes.

---

Google Calendar Integration 🔗

For Google Calendar webhook integration, use the PATCH /user endpoint to update follow_up_datetime when calendar events are created or modified.

Webhook Flow:

User creates/updates event in Google Calendar
Google sends webhook to your endpoint
Your webhook handler extracts client ID from event metadata
Call API to update client's follow_up_datetime

Example Webhook Handler:

curl -X PATCH "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 6,
    "follow_up_datetime": "2026-02-15 14:30:00",
    "add_note": "Meeting scheduled via Google Calendar"
  }'

---

API Testing 🔗

Test WhatsApp Integration 🔗

Test creating a client with WhatsApp fields:

curl -X POST "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Test WhatsApp User",
    "email": "[email protected]", 
    "phone": "050-1234567",
    "whatsapp_username": "testuser2026",
    "additional_phone": "052-9876543",
    "city": "Tel Aviv",
    "address": "123 Test Street",
    "client_group": "group1",
    "user_tags": ["tag1", "tag2"],
    "initial_note": "Test user created via API with WhatsApp fields",
    "source": "API Test - WhatsApp Integration",
    "consent_given": true,
    "newsletter_signup": false
  }'

Expected Response: HTTP 201 with full user data including WhatsApp fields.

Test Duplicate Detection 🔗

Test duplicate by email (should update existing):

curl -X POST "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Test WhatsApp User Updated",
    "email": "[email protected]",
    "whatsapp_username": "updateduser2026",
    "source": "API Test - Duplicate Detection",
    "consent_given": false,
    "newsletter_signup": true
  }'

Expected Response: HTTP 200 with updated user data and note about the update.

Test Field Updates 🔗

Test updating WhatsApp fields only:

curl -X PATCH "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": USER_ID_HERE,
    "whatsapp_username": "newusername2026",
    "additional_phone": "053-1111111",
    "add_note": "Updated WhatsApp contact information"
  }'

Expected Response: HTTP 200 with updated fields and new note in timeline.

Validation Tests 🔗

Test invalid WhatsApp username (should still work):

curl -X POST "https://yourdomain.com/wp-json/crm/v2/user" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Invalid WhatsApp Test",
    "whatsapp_username": "@invalidformat",
    "source": "API Test - Validation"
  }'

Expected Response: HTTP 201 - API accepts any string for WhatsApp username (validation handled by client applications).

---

Rate Limiting & Best Practices 🔗

API Limits 🔗

No built-in rate limiting (implement on your end if needed)
Webhooks have 5-second timeout
Non-blocking webhook delivery

Best Practices 🔗

Authentication:

Use headers instead of query parameters for API keys
Store API credentials securely
Rotate keys periodically

Data Handling:

Always check for duplicate detection responses (200 vs 201)
Handle both phone and WhatsApp contact methods
Use source field to track integration origins
Add meaningful notes for audit trails

Error Handling:

Implement retry logic for 5xx errors
Log API responses for debugging
Handle network timeouts gracefully

WhatsApp Integration:

Store usernames without @ symbol
Validate usernames on client side before sending
Plan for 2026 transition to username-primary workflows
Use additional_phone for backup contact methods

SuperBook CRM API Documentation 🔗

Setup 🔗

Authentication 🔗

Base URL 🔗

Important Notes 🔗

Endpoints 🔗

1. Get Single User 🔗

2. List Users 🔗

3. Create User 🔗

4. Update User 🔗

5. Delete User 🔗

6. Toggle User Tag 🔗

Client Groups 🔗

User Tags 🔗

Consent & Newsletter Management 🔗

Consent Fields 🔗

Legal Compliance Features 🔗

Form Integration 🔗

API Examples 🔗

Response Format 🔗

WhatsApp Integration (2026 Ready) 🔗

WhatsApp Fields 🔗

WhatsApp API Examples 🔗

Migration Strategy 🔗

Phone Number Normalization 🔗

Error Responses 🔗

Webhooks 🔗

Webhook Events 🔗

Webhook Payload Structure 🔗

Event-Specific Data 🔗

Webhook Configuration 🔗

Google Calendar Integration 🔗

API Testing 🔗

Test WhatsApp Integration 🔗

Test Duplicate Detection 🔗

Test Field Updates 🔗

Validation Tests 🔗

Rate Limiting & Best Practices 🔗

API Limits 🔗

Best Practices 🔗