Smbcrm Advanced Tools

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:

1. Clarify the business outcome
2. Pick the simplest working tool
3. Define the required data objects
4. Define the required scopes/permissions
5. Provide a copy/paste-ready implementation
6. Include a test plan
7. Include failure modes / rollback

Prefer these solution types in this order:

1. Native workflow only
2. Workflow + webhook action
3. Private Integration Token + REST API
4. Private Integration Token + MCP
5. 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/.

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:

1. Click "Create new Integration"
2. Name it clearly by purpose and environment
3. Select only required scopes
4. Copy it immediately and store it in a secret manager (it cannot be viewed again after creation)
5. 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:

1. Resolve the correct pipeline and stage IDs
2. Confirm ownership / assignment rules
3. Move the opportunity
4. 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:

1. Fetch field definitions first
2. Map by stable identifiers, not display labels alone
3. 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.

1. Trigger on intake event
2. Normalize data
3. Apply tags
4. Set fields and lead source
5. Create or move opportunity
6. Assign owner
7. Start follow-up sequence
8. Notify internal team if needed

Pattern 2 — SLA timer and escalation

Use when speed-to-lead matters.

1. Trigger on new lead or stage entry
2. Wait fixed interval
3. Check for reply / call / stage movement
4. Escalate to manager or reassign
5. 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.

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