Connecting SMOC with the REST API

Simple guide showing how to connect to the SMOC REST API from your own code, sync jobs, or CRM pipelines. The API is company-scoped and read-only. Console Settings → Integrations → API shows the base URL for the environment you are in.

Get your API key

1. Go to Settings → Integrations → API in SMOC Console.
2. Generate a new key and copy it immediately — it's shown only once, so store it somewhere secure.

Your key is tied to your company. Every request made with it is automatically scoped to your data. Generating a new key does not revoke existing keys.

Base URLs

Environment	Base URL
Production	https://v2.api.smoc.ai
Staging	https://v2-staging.api.smoc.ai

Full contacts endpoint on production:

GET https://v2.api.smoc.ai/api/company/mongocontact

Authentication

Send the key in a custom HTTP header named token — not Authorization: Bearer.

GET /api/company/mongocontact HTTP/1.1
Host: v2.api.smoc.ai
token: YOUR_SMOC_API_KEY

Do not use Clerk secret keys (sk_…) or publishable keys (pk_…).

What functions exist

The public REST API currently exposes one function:

List company contacts — GET /api/company/mongocontact

Returns a page of contacts for the company on the key, plus aggregate counts.

What it returns

• Contact records: name, email, phone, status, address, last conversation date, visit/UTM history, survey answers, custom text fields, referral and promo data when collected. Positive message-flow smart leads are standard leads (status: "1") and also include leadSentiment, leadCapturedAt, and tags when present.
• leadsCount — contacts with status lead (including unset)
• customerCount — contacts with status customer

Counts cover all company contacts, not only the current page.

Query parameters

Parameter	Default	Description
limit	100	Max contacts to return (1–500)
sortByField	(none)	Sort descending by createdAt, updatedAt, lastConversationDate, or leadCapturedAt
status	(none)	Filter by contact status. status=1 is the standard lead poll and includes positive message-flow smart leads

Contact status values: "1" lead, "2" customer, "3" lost, "4" converted.

There are no write endpoints: you cannot create, update, or delete contacts through this API. There is no cursor pagination — use limit and track seen IDs client-side, or use Zapier polling.

Field-level response shapes are in the Public Contacts API reference.

Example request

curl -s \
  -H "token: YOUR_SMOC_API_KEY" \
  "https://v2.api.smoc.ai/api/company/mongocontact?status=1&limit=25&sortByField=leadCapturedAt"

What is not on the REST API

Inbox threads, message-flow conversations, flowcharts, company assets, and flow analytics are not REST endpoints. Use SMOC MCP from Claude, Cursor, or VS Code for those read tools.

Security notes

• The key is shown once at creation — store it in a password manager or environment variable.
• Never commit the key to a Git repository.
• All access is read-only and confined to your company's data.

Troubleshooting

• 401 Missing token header: send token: <key>, not Authorization: Bearer.
• 401 Invalid or revoked token: confirm the key is correct and has not been revoked.
• 422 limit must not exceed 500: lower the limit query parameter.
• 422 Invalid status value: use 1, 2, 3, or 4.