SMOC REST v2 API reference

REST v2 is the public HTTP API for company data. Every domain tool uses the same JSON body as the matching MCP tool. Customer keys are read-only by default and scoped to your company. Write-enabled keys may call the limited write tools below. GET /api/company/mongocontact is unchanged for Zapier.

Base URL

https://api.smoc.ai

Machine-readable catalog: GET /api/v2 or GET /api/v2/openapi.json.

Auth

Send a key from Settings → Integrations → API (or MCP) as Authorization: Bearer <key> or the legacy token header.

curl -s -X POST https://api.smoc.ai/api/v2/whoami \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Do not use Clerk sk_… or pk_… keys.

Shape

POST /api/v2/{toolName} with Content-Type: application/json.

Success is HTTP 200 with a JSON object. Errors are 4xx with { "code", "error", "details?" }. Common codes: MISSING_BEARER_TOKEN, INVALID_INPUT, TOOL_DENIED, FLOWCHART_NOT_FOUND.

Customer keys do not send companyId. The key already selects the company.

GET|POST /api/v2/whoami is on REST. Discovery tools mcp_capabilities, skills_search, and skills_get stay on MCP only (https://api.smoc.ai/mcp).

Identity

GET|POST /api/v2/whoami

Returns role, company scope, permissions, token kind, and environment. Body optional.

Company

Call	Body	Returns
POST /api/v2/companies_get	{}	Company profile (title, key, URL, languages, settings)
POST /api/v2/company_assets_get	{}	Products, positioning, website links, files
POST /api/v2/settings_notifications_get	{}	Notification preference summary (no email addresses)

Company asset extractions

Permission: company:read or cpcs:read.

Call	Body	Returns
POST /api/v2/company_asset_extraction_results_list	limit? (1–100), includeData?, statuses?, templateNameKey?, tag?	Extraction result summaries
POST /api/v2/company_asset_extraction_results_get	resultId (required), includeData?	One result
POST /api/v2/company_asset_extraction_templates_list	limit?, templateNameKey?, tag?	Template / tag / freshness summaries

Contacts

Permission: contacts:read.

Call	Body	Returns
POST /api/v2/contacts_search	Filters below, plus page?, pageSize? (1–100), sortBy?, sortDirection? (asc | desc)	Paginated contacts
POST /api/v2/contacts_get	contactId (required)	One sanitized contact
POST /api/v2/contacts_get_stats	Same filters as search (no page)	Counts and engagement summary
POST /api/v2/contacts_get_filter_options	Same filters, plus optionLimit? (1–200)	Valid filter values
POST /api/v2/contact_tags_list	{}	Contact tags
POST /api/v2/prospect_lists_list	{}	Prospect lists
POST /api/v2/prospect_lists_get	listId (required)	One prospect list

Contact filters (all optional): dateFrom, dateTo (YYYY-MM-DD), search (max 200), location, flow, surveyQuestionAnswer, promosRedeemed, profileInfo, device, os, browser, utmSource, utmMedium, utmCampaign (string or array of up to 50), surveyLanguage, firstName, lastName, msisdn, company, city, street, zip, brandId, status.

sortBy: createdAt, updatedAt, lastConversationDate, email, firstName, lastName, company, city, status.

curl -s -X POST https://api.smoc.ai/api/v2/contacts_search \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"search":"ada","pageSize":20,"sortBy":"updatedAt","sortDirection":"desc"}'

Zapier / compat contacts remain GET /api/company/mongocontact with the token header. Field-level mongocontact shapes: Public Contacts API.

Inbox and conversations

Permission: inbox:read for reads. Write-enabled keys also need inbox:write for triage and text send.

Call	Body	Returns
POST /api/v2/inbox_threads_list	q?, sender?, flowId?, contactId?, companyUserId?, conversationId?, inboxFolder? (inbox | archived | all), unreadOnly?, unansweredOnly?, page?, limit? (1–50)	Threads
POST /api/v2/inbox_threads_get	threadId (required), includeMessages?	One thread
POST /api/v2/inbox_messages_list	threadId (required), limit? (1–200)	Messages, including merged peer threads
POST /api/v2/conversations_list	flowId?, contactId?, conversationId?, q?, page?, limit? (1–50)	Message-flow runs
POST /api/v2/conversations_get	conversationId (required)	One run, including milestones
POST /api/v2/inbox_threads_archive	threadId	Archives a thread
POST /api/v2/inbox_threads_unread	threadId	Marks a thread unread
POST /api/v2/inbox_threads_mark_handled	threadId	Marks unanswered handled
POST /api/v2/inbox_threads_send	threadId, body, idempotencyKey	Sends a text-only reply

curl -s -X POST https://api.smoc.ai/api/v2/inbox_threads_list \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unansweredOnly":true,"limit":25}'

Outreach

Call	Permission	Body	Returns
POST /api/v2/outreach_accounts_list	inbox:read	{}	LinkedIn / outreach account status
POST /api/v2/outreach_contacts_import_get	contacts:read	importJobId (required)	Contact import / enrichment job status

Flowcharts and Studio

Permission: flowcharts:read. Use uniqueFlowchartId from flowcharts_list as flowchartId when a catalog numeric id is missing.

Call	Body	Returns
POST /api/v2/flowcharts_list	name?, operatorKey?, conversationTemplateKey?, status? (draft | published), page?, limit? (1–100)	Flowchart summaries
POST /api/v2/flowcharts_get	flowchartId (required), detail? (summary | full)	One flowchart (full includes the graph)
POST /api/v2/flowchart_recommendations_list	flowchartId (required)	Recommendation documents
POST /api/v2/flowcharts_versions_list	flowchartId (required)	Version ids, dates, status
POST /api/v2/themes_get	operatorKey?	Theme for the company (or operator key)
POST /api/v2/message_flow_settings_get	flowchartId (required)	Message-flow / conversation-template settings
POST /api/v2/message_flow_settings_summary	flowchartId (required)	Channel id, locale, active flag
POST /api/v2/message_flow_contacts_list	flowchartId (required)	Recent conversation / contact rows
POST /api/v2/message_flow_kpis_get	flowchartId (required)	Conversation totals
POST /api/v2/targeting_portfolios_list	flowchartId (required)	Targeting portfolios
POST /api/v2/targeting_portfolios_get	portfolioId (required)	One portfolio
POST /api/v2/studio_generations_get	jobId (required; generationId also accepted)	Generation job
POST /api/v2/studio_translations_get	jobId (required; translationId also accepted)	Translation job
POST /api/v2/studio_generation_categories_list	executionFlowType? (web | message)	Generation categories for that flow type

Super-user keys with flowchart writes enabled can also edit Mongo drafts. These calls do not publish, toggle live, or enroll a first batch. Publishing stays a button in Studio or Console.

Call	Body	Returns
POST /api/v2/flowcharts_create	name, flowType? (web | message), webFormat? (chat | card)	New draft identity
POST /api/v2/flowcharts_duplicate	flowchartId, name?	Copy as a new draft
POST /api/v2/flowcharts_save	flowchartId, flowchart, expectedRevision?	Saved draft revision
POST /api/v2/flowcharts_restore_version	flowchartId, versionId	Restored draft
POST /api/v2/themes_save	operatorKey, operatorChannelKey, theme	Theme draft revision
POST /api/v2/flowchart_recommendation_item_update	docId, index, status (applied | rejected)	Updated item
POST /api/v2/targeting_portfolio_update	portfolioId, patch (status?, provider?, dimensions?)	Updated portfolio

flowcharts_save accepts flowType web or message, channel, and webFormat chat or card on the graph metadata. Web flows use channel chat. Message flows use linkedin, email, or whatsapp. The save keeps the stored active flag.

curl -s -X POST https://api.smoc.ai/api/v2/flowchart_recommendations_list \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"flowchartId":"YOUR_UNIQUE_FLOWCHART_ID"}'

Analytics

Permission: analytics:read. Dates are YYYY-MM-DD. Shared optional filters: startDate, endDate, flowId, flowVersionId, deviceType, os, country, languageCode, utmSource, utmMedium, utmCampaign.

Call	Extra body	Returns
POST /api/v2/analytics_flow_list_flows	Shared filters	Flows ranked by traffic
POST /api/v2/analytics_flow_kpis	Shared filters	Totals and previous-period deltas
POST /api/v2/analytics_flow_timeseries	Shared filters, granularity? (day | month)	Daily or monthly series
POST /api/v2/analytics_flow_dimension_metrics	Shared filters, dimension (required), limit? (1–200)	Breakdown
POST /api/v2/analytics_flow_filter_values	Shared filters	Valid filter values
POST /api/v2/edge_visit_counts_get	conversationTemplateId (required), startDate?, endDate?	Edge-visit counts

dimension must be one of: deviceType, os, country, languageCode, utmSource, utmMedium, utmCampaign, dayOfWeek.

curl -s -X POST https://api.smoc.ai/api/v2/analytics_flow_kpis \
  -H "Authorization: Bearer YOUR_SMOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"startDate":"2026-08-01","endDate":"2026-08-31"}'

Website scan (CPCS)

Permission: cpcs:read.

Call	Body	Returns
POST /api/v2/cpcs_overview	{}	Project, crawl, extraction, and schedule overview
POST /api/v2/cpcs_urls_list	{}	Webpage / link URLs used for crawls
POST /api/v2/cpcs_crawls_get	crawlId (required), projectId?	One crawl job
POST /api/v2/cpcs_extractions_get	extractionId (required), projectId?	One extraction job
POST /api/v2/cpcs_list_templates	{}	Extraction templates
POST /api/v2/cpcs_schedule_get	{}	Crawl schedule

Writes (opt-in)

Default keys stay read-only. When you check Allow limited writes in Console, the key can call contacts/tags/lists create-update, company profile / assets basics, cpcs_urls_add, flowchart rename / recommendation status, inbox triage, and inbox_threads_send.

What customer keys cannot do

Write-enabled customer keys still cannot delete data, edit flow graphs, publish flows, toggle live, change targeting, start credit-burning jobs, or send LinkedIn outreach campaigns. Super-user keys can save flow and theme drafts and patch targeting dimensions on MCP and REST v2; they still cannot publish. GET /api/company/mongocontact stays the Zapier/compat contacts contract.

MCP

The same tools are available to Claude, Cursor, and VS Code at https://api.smoc.ai/mcp. Setup: MCP eGuide. Connection walkthrough: REST connection guide.

See also

• Connecting SMOC with the REST API
• Public Contacts API
• MCP for Claude, Cursor, and VS Code
• Integrating collected customer data