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. Customer keys are company-scoped and read-only by default. Write-enabled keys may call limited writes including inbox send; they cannot edit flow graphs, publish flows, or start LinkedIn outreach campaigns. Super-user keys can save flow and theme drafts on the same POST /api/v2/{toolName} calls; publishing still requires a person in Studio or Console. Domain tools live on REST v2 as POST /api/v2/{toolName} (same handlers as MCP). Full call list: REST v2 API reference. GET /api/company/mongocontact stays for Zapier.

Get your API key

1. Go to Settings → Integrations → API in SMOC Console.
2. Optionally give the key a name and an expiry (7, 30, or 90 days). Leave expiry on No expiry if you do not want it to expire.
3. Generate the 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. Issued keys are listed on the same page — revoke unused keys there. The MCP page uses the same controls — see the screenshot in the MCP guide.

Base URL

Base URL: https://api.smoc.ai

Full contacts endpoint:

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

Authentication

Legacy contacts: send the key in a custom HTTP header named token. REST v2 accepts Authorization: Bearer or token.

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

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

What functions exist

REST v2 — POST /api/v2/{toolName}

Mirrors MCP domain tools (contacts_search, cpcs_overview, inbox_threads_list, and the rest). OpenAPI: GET /api/v2 or GET /api/v2/openapi.json. See the REST v2 reference.

List company contacts — GET /api/company/mongocontact (Zapier / compat)

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.

Customer keys cannot create, update, or delete contacts. There is no cursor pagination on mongocontact — use limit and track seen IDs client-side, or use Zapier polling. Richer search is POST /api/v2/contacts_search.

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

Example request

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

What is not on the customer API

Write-enabled keys still cannot publish a flow, toggle live (flowcharts_set_active), delete records, or start a LinkedIn outreach campaign. Inbox send is opt-in on a write-enabled key (inbox_threads_send, text only, requires idempotencyKey). Use SMOC MCP from Claude, Cursor, or VS Code for the same tools over MCP.

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.
• Customer keys are confined to your company's data. Default keys are read-only; writes including inbox send are opt-in.
• Revoke unused keys from the issued-keys list on Settings → Integrations → API.

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.

See also

• REST v2 API reference — every POST /api/v2/{toolName} call
• Connecting SMOC with the REST API
• Public Contacts API
• MCP for Claude, Cursor, and VS Code