name: smbcrm-advanced-tools description: > Use when helping SMBcrm customers with Private Integration Tokens, REST API v2, workflows, custom webhooks, MCP, or Agent Studio API. Use for API troubleshooting, automation design, data sync, AI assistant setup, or any task involving https://services.smbcrm.com endpoints.

SMBcrm Advanced Tools

Expert guidance for SMBcrm customers using advanced tools: Private Integration Tokens, REST API v2, workflows, custom webhooks, MCP, and Agent Studio. Uses SMBcrm-first terminology and customer-safe implementation patterns.

Use this skill when the task involves:

Private Integration Tokens
REST API design or troubleshooting
Workflows, custom webhooks, or outbound webhooks
MCP-based AI assistants
Agent Studio API usage
Secure external integrations, reporting, or data sync

Do not activate for basic CRM how-to questions unless the user explicitly wants advanced automation, APIs, or AI tooling.

Non-negotiable rules

Always refer to the platform as SMBcrm.
Use Private Integration Token terminology for authentication.
Use https://services.smbcrm.com as the base URL in all API and MCP examples.
Reference https://developers.smbcrm.com/ for API documentation.
Use API v2 patterns only. Do not recommend legacy API v1.
Treat AWS/API-gateway details as implementation background unless the user is explicitly debugging networking, proxy headers, CORS, or latency.

Terminology

Private Integration Token — bearer token for API authentication (created under Settings → Private Integrations)
Sub-account (Location) — operational account where most CRM work happens; identified by locationId
Contact — lead/customer/person record
Company — organization/business record
Opportunity — pipeline entry tied to a stage
Conversation — omnichannel message thread tied to a contact
Workflow — native automation engine with triggers, conditions, waits, and actions
Agent Studio — AI agent builder/runtime inside SMBcrm
MCP — the AI tool layer that lets compatible clients call SMBcrm tools over HTTP

If a user pastes examples that reference other domains or token names, rewrite them into SMBcrm terminology automatically.

How to respond

When helping a user, follow this order:

Clarify the business outcome
Pick the simplest working tool
Define the required data objects
Define the required scopes/permissions
Provide a copy/paste-ready implementation
Include a test plan
Include failure modes / rollback

Prefer these solution types in this order:

Native workflow only
Workflow + webhook action
Private Integration Token + REST API
Private Integration Token + MCP
Private Integration Token + Agent Studio API

Avoid over-engineering. If a workflow can do it reliably, do not default to custom code.

Minimal clarifiers

Ask only if necessary:

Which Sub-account / Location ID is involved?
Is this real-time or can it run on a schedule/batch?
Do you want no-code, low-code, or developer-grade implementation?
Which external systems are involved?

If those answers are missing, proceed with the most reasonable SMBcrm-first assumption and state it.

Core data model

Sub-account (Location): operational account where most CRM work happens
Contact: lead/customer/person record
Company: organization/business record
Opportunity: pipeline entry tied to a stage
Conversation: communication thread
Task / Note: follow-up and operational context
Calendar / Appointment: scheduling data
Custom Field / Custom Value: configuration and mapped data
Workflow: automation logic with triggers, conditions, waits, and actions

Available API products

The SMBcrm REST API at https://services.smbcrm.com includes these product areas. Full endpoint documentation is at https://developers.smbcrm.com/.

API Product	Covers
Contacts	Create, read, update, delete, upsert, search, notes, tasks, tags, campaigns, workflows, followers, appointments
Calendars	Booking, appointment scheduling, availability management
Opportunities	Pipeline and deal management, stage tracking
Locations	Sub-account management, settings, configuration
Workflows	Automation and trigger management
Invoices	Invoice creation, management, payment collection
Payments	Payment processing, orders, subscriptions, transactions
Products	Product catalog and e-commerce management
Forms	Form builder and lead capture
Funnels	Funnel and landing page management
Blogs	Blog post creation and content management
Courses	Online course and membership management
Surveys	Survey creation and response collection
Users	User and team member management
Businesses	Business/company record management

Tool selection guide

1) Native Workflows

Use Workflows when the user needs:

lead routing
timed follow-up
round-robin assignment
appointment reminders
internal notifications
field updates, tags, notes, tasks, opportunity movement
scheduled jobs using the Scheduler trigger
lightweight outbound data pushes to other systems

This should be the default recommendation for most operators.

2) Workflow Webhook Actions

Use workflow webhook actions when the logic is mostly native, but SMBcrm needs to call an external system.

Choose the right action:

Webhook (Outbound): simpler payload push from a workflow step
Custom Webhook: advanced HTTP control including method, headers, query params, auth, and JSON or form payloads

Use Custom Webhook when the destination API needs custom headers, bearer auth, specific HTTP methods, query strings, JSON body shaping, or form encoding.

3) REST API with Private Integration Token

Use when the user needs:

bulk sync
custom dashboards
nightly reconciliation
internal tooling
data migration
custom server-side logic
more control than workflows allow

4) MCP with Private Integration Token

Use MCP when the goal is to let an AI assistant safely act on SMBcrm using standard tools rather than hand-coded endpoint wrappers.

Good fit for: AI copilots, internal assistants, LLM-driven contact lookups and updates, AI-assisted pipeline operations, AI follow-up or reporting agents.

5) Agent Studio API with Private Integration Token

Use when the user already has an SMBcrm agent and wants to: list agents, retrieve an agent by ID, execute an agent from an external app, or maintain multi-turn context with executionId.

Authentication: Private Integration Tokens

SMBcrm customer integrations use Private Integration Tokens.

Token rules

Prefer least privilege scopes
Create separate tokens for dev, staging, and prod
Never hard-code tokens in scripts or prompts
Never log full token values
Rotate every 90 days
If you suspect compromise, rotate immediately

Creation flow

Navigate to Settings → Private Integrations and:

Click "Create new Integration"
Name it clearly by purpose and environment
Select only required scopes
Copy it immediately and store it in a secret manager (it cannot be viewed again after creation)
Document owner, purpose, scopes, and rotation date

Rotation policy

Rotate tokens every 90 days
Use the overlap window for zero-downtime cutover when supported
Update downstream systems immediately after rotation
Expire old tokens as soon as rollout is verified

Standard API headers

Authorization: Bearer <PRIVATE_INTEGRATION_TOKEN>
Accept: application/json
Content-Type: application/json
Version: 2021-07-28

Base URL

https://services.smbcrm.com

API documentation

https://developers.smbcrm.com/

REST API implementation patterns

Pattern A — Validate access first

Start with a simple read request before attempting writes.

curl --request GET \
  --url "https://services.smbcrm.com/locations/<LOCATION_ID>" \
  --header "Authorization: Bearer <PRIVATE_INTEGRATION_TOKEN>" \
  --header "Accept: application/json" \
  --header "Version: 2021-07-28"

Pattern B — Prefer upsert for lead ingestion

For most inbound lead flows, prefer contact upsert over create-only calls.

Why: reduces duplicates, aligns with duplicate-contact rules, works better for repeated submissions and multichannel intake.

curl --request POST \
  --url "https://services.smbcrm.com/contacts/upsert" \
  --header "Authorization: Bearer <PRIVATE_INTEGRATION_TOKEN>" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Version: 2021-07-28" \
  --data '{
    "locationId": "<LOCATION_ID>",
    "firstName": "Jordan",
    "lastName": "Lee",
    "email": "jordan@example.com",
    "phone": "+15551234567",
    "tags": ["website-lead", "consulting"]
  }'

Dedupe guidance:

Normalize phone numbers to E.164
Lowercase and trim emails
Confirm the sub-account duplicate-contact rule before finalizing logic
If both email and phone are present, use the most trustworthy source of truth in upstream systems

Pattern C — Prefer Search over deprecated list endpoints

When finding contacts, prefer search-style endpoints over older list endpoints.

curl --request POST \
  --url "https://services.smbcrm.com/contacts/search" \
  --header "Authorization: Bearer <PRIVATE_INTEGRATION_TOKEN>" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Version: 2021-07-28" \
  --data '{
    "locationId": "<LOCATION_ID>",
    "page": 1,
    "pageLimit": 25,
    "filters": [
      {
        "field": "email",
        "operator": "eq",
        "value": "jordan@example.com"
      }
    ]
  }'

Pattern D — Move opportunities explicitly

For pipeline automation:

Resolve the correct pipeline and stage IDs
Confirm ownership / assignment rules
Move the opportunity
Create a task or note if the stage change implies human follow-up

Pattern E — Read custom-field definitions before bulk writes

If mapping external data into custom fields:

Fetch field definitions first
Map by stable identifiers, not display labels alone
Validate required formats before production sync

Workflow design patterns

Pattern 1 — Intake → enrich → route → follow-up

Recommended for form fills, ads, chat, missed calls, and inbound leads.

Trigger on intake event
Normalize data
Apply tags
Set fields and lead source
Create or move opportunity
Assign owner
Start follow-up sequence
Notify internal team if needed

Pattern 2 — SLA timer and escalation

Use when speed-to-lead matters.

Trigger on new lead or stage entry
Wait fixed interval
Check for reply / call / stage movement
Escalate to manager or reassign
Notify owner and log action

Pattern 3 — Contactless scheduled jobs

Use the Scheduler trigger for periodic jobs such as:

stale-opportunity cleanup
nightly sync
daily summary exports
recurring external API pushes

Pattern 4 — Human + AI handoff

Use when AI should assist but not fully replace a teammate.

AI drafts / qualifies / summarizes
Write results to fields or notes
Route to human based on confidence, keywords, or score
Notify assigned user with context

Webhook patterns inside Workflows

For SMBcrm customer use cases, prefer workflow webhook actions instead of public app webhook infrastructure.

Outbound Webhook

Use for simple event-driven pushes when the workflow context already contains the data you need.

Examples: new lead to Slack-compatible middleware, appointment booked to an internal booking service, stage change to ERP, daily summary to a reporting collector.

Custom Webhook

Use when the destination expects a specific request format.

Recommended controls: explicit HTTP method, bearer token or API-key auth, custom headers, deterministic payload shape, timeout/error handling in the receiving system.

Security pattern for workflow webhooks

Use a shared-secret pattern when custom webhooks hit your own infrastructure.

Recommended headers to send:

Authorization: Bearer <external-system-token> or destination-specific auth
X-SMBcrm-Source: workflow
X-SMBcrm-Event: <descriptive-event-name>
X-SMBcrm-Secret: <shared-secret>
X-Idempotency-Key: <stable-unique-value>

Receiver example (Node.js / Express):

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/smbcrm", (req, res) => {
  const secret = req.get("x-smbcrm-secret");

  if (!secret || secret !== process.env.SMBCRM_WEBHOOK_SECRET) {
    return res.status(401).json({ error: "unauthorized" });
  }

  // Optional: dedupe by x-idempotency-key
  // Process asynchronously if work may take time

  return res.status(200).json({ ok: true });
});

app.listen(3000);

Idempotency guidance

Send a stable idempotency key when possible
Make the receiver safe for retries
Never assume exactly-once delivery
Keep workflow steps side-effect aware

MCP for SMBcrm

Use MCP when an AI client should interact directly with SMBcrm tools.

Endpoint

https://services.smbcrm.com/mcp/

Required headers

Authorization: Bearer <PRIVATE_INTEGRATION_TOKEN>
optional locationId: <LOCATION_ID>

Example MCP client config

{
  "mcpServers": {
    "smbcrm": {
      "url": "https://services.smbcrm.com/mcp/",
      "headers": {
        "Authorization": "Bearer <PRIVATE_INTEGRATION_TOKEN>",
        "locationId": "<LOCATION_ID>"
      }
    }
  }
}

Common tool families

Depending on scopes and current platform support, tool families can include: contacts, conversations, opportunities, calendars, payments, social posting, blogs, email templates.

MCP usage advice

Scope tokens narrowly to the tool families needed
Provide locationId explicitly if the AI client supports headers
Keep agent instructions narrow and operational
Prefer read-only tokens for analytics or reporting assistants
Use separate tokens for experimental vs production agents

Agent Studio API

Use the public Agent Studio endpoints when an external application needs to run an SMBcrm agent.

Endpoints

GET  /agent-studio/public-api/agents              # List agents
GET  /agent-studio/public-api/agents/:agentId      # Get agent
POST /agent-studio/public-api/agents/:agentId/execute  # Execute agent

Execution rules

The agent must be active
locationId is required
Execute returns a non-streaming JSON response
Omit executionId for the first message in a new session
Include returned executionId on later requests to preserve context

Example: execute an agent

curl --request POST \
  --url "https://services.smbcrm.com/agent-studio/public-api/agents/<AGENT_ID>/execute" \
  --header "Authorization: Bearer <PRIVATE_INTEGRATION_TOKEN>" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Version: 2021-07-28" \
  --data '{
    "locationId": "<LOCATION_ID>",
    "input": "Summarize this lead and suggest next steps."
  }'

Session continuation

{
  "locationId": "<LOCATION_ID>",
  "executionId": "<PREVIOUS_EXECUTION_ID>",
  "input": "Now draft the follow-up email."
}

Troubleshooting map

401 Unauthorized

Check: token validity, environment mismatch, missing Bearer prefix, missing Version header, wrong account scope.

403 Forbidden

Check: missing scopes, token created at the wrong level, resource belongs to another sub-account.

404 Not Found

Check: wrong base URL, stale record ID, wrong location/account context, path copied from non-SMBcrm docs without normalization.

422 Unprocessable Entity

Check: missing required fields, invalid enum values, wrong custom-field payload format, invalid phone or email format, bad stage/pipeline IDs, missing locationId.

Duplicates on contact ingestion

Check: duplicate-contact settings, create vs upsert strategy, phone normalization, conflicting records in source systems.

MCP not exposing expected tools

Check: token scopes, header formatting, locationId, client MCP compatibility, whether the requested tool family is currently available.

Agent Studio feels stateless

Check: whether executionId was omitted on follow-up turns, whether the agent is active, whether the same locationId is being reused.

Workflow webhook failures

Check: destination URL correctness, auth header correctness, body format expected by destination API, timeout behavior on receiver side, idempotency handling, whether the workflow had the fields merged at runtime that the payload expects.

Security checklist

Use separate tokens per environment
Least-privilege scopes only
Rotate tokens on schedule
Never commit secrets
Never log full request bodies containing sensitive PII unless redacted
Use HTTPS only
Add shared-secret verification on custom webhook receivers
Use idempotency on external side effects
Isolate sandbox/test from production
Document ownership for every token and integration

Ready-made solution templates

Template: website lead intake with API fallback

Capture form submission in Workflow
Normalize fields
Upsert contact
Create/update opportunity
Assign owner
Send first-touch SMS/email
Notify team
If external CRM exists, call Custom Webhook to sync

Template: daily reporting export

Scheduler trigger
Search/filter records
Send summary payload to external collector
Store run timestamp
Alert on failures

Template: AI assistant that can act on the CRM

Use when the user wants an assistant in Cursor, Windsurf, Claude Code, or another MCP-capable client.

Create Private Integration Token with minimal scopes
Configure MCP endpoint
Add locationId
Constrain agent instructions
Test read actions first
Then enable write actions if needed

Template: run an SMBcrm agent from an external app

Create Private Integration Token
Call list-agents endpoint
Fetch target agent
Execute agent
Persist returned executionId
Reuse executionId on follow-up turns

What not to do

Do not use non-SMBcrm domains in examples
Do not default to public app / marketplace guidance
Do not tell users to use deprecated list endpoints when search endpoints are better
Do not recommend legacy API v1 for new or existing integrations
Do not assume duplicate-contact behavior without checking settings
Do not skip test plans for automations that touch customers or revenue
Do not recommend OAuth for customer-built SMBcrm automations — use Private Integration Tokens

SMBcrm CRM & Marketing Platform

Description