SMOC Public Contacts API — Integrationsguide

Guide till SMOC Public Contacts API — ett skrivskyddat REST-endpoint för att lista kontakter och aggregerade antal för ditt företag. Använd det från egna integrationer, synkroniseringsjobb eller tillsammans med Zapier-appen.

Översikt

SMOC Public API låter tredjepartssystem läsa kontakter för ett enda företag. Det är hostat på Cloudflare Workers och avgränsas automatiskt till det företag som är kopplat till din API-nyckel.

Vad det gör idag:

• Listar kontakter för ditt företag (upp till 500 per förfrågan)
• Returnerar aggregerade antal leads och kunder
• Avgränsar data automatiskt till företaget kopplat till din API-nyckel

Vad det inte gör:

• Skapar, uppdaterar eller tar bort kontakter
• Paginering med cursors eller offset (endast ett limit-tak)
• Fråga över flera företag med en nyckel

Detta Zapier/compat-kontrakt kvarstår. Det enda kontakt-endpointet för det kontraktet är:

GET /api/company/mongocontact

Rikare kontakt-sökning är tillägg: POST /api/v2/contacts_search. Migrera inte Zapier från mongocontact.

För Console-setup, autentisering och funktionsöversikt, börja med REST API-anslutningsguiden.

Hämta din API-nyckel

Alla SMOC-dataintegrationer använder samma Console-tokenmönster som Zapier och MCP:

1. Logga in på SMOC Console.
2. Gå till Inställningar → Integrationer → API (använd Integrationer → Zapier för Zapier-specifik setup).
3. Namnge eventuellt nyckeln och sätt ett utgångsdatum, klicka sedan på Generera ny API-nyckel.
4. Kopiera nyckeln direkt — den visas bara en gång och kan inte hämtas senare.

Att generera en ny nyckel avbryter inte befintliga nycklar. Utfärdade nycklar listas på samma sida — återkalla oanvända nycklar där när du behöver rotera behörigheter.

Varje nyckel är bunden till ett företag. Nyckeln bär ett operatorId-anspråk lika med det företagets ID. API:et använder detta för att avgränsa all kontaktdata — du kan inte ange ett annat företags-ID i förfrågan.

Basadresser

Miljö	Basadress
Produktion	https://api.smoc.ai

Fullständigt endpoint-exempel:

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

Autentisering

Skicka din API-nyckel i en anpassad HTTP-header med namnet token:

GET /api/company/mongocontact HTTP/1.1
Host: api.smoc.ai
token: <your-api-key>
Content-Type: application/json

API:et verifierar nyckeln och läser operatorId-anspråket för att avgöra vilket företags kontakter som ska returneras. Du skickar inte ett företags-ID i URL:en eller frågesträngen.

Använd inte:

• Authorization: Bearer … — denna header accepteras inte av detta endpoint (trots vad Console-sidan "API Access" kan visa just nu). Använd token-headern i integrationer tills produktsupport för Bearer läggs till.
• Clerk secret keys (sk_…) eller publishable keys (pk_…) — dessa avvisas med 401 Invalid token type.

Förfrågan

Metod: Endast GET. Andra metoder (t.ex. POST) returnerar 404 Not Found.

Query-parametrar

Parameter	Typ	Obligatorisk	Standard	Beskrivning
limit	integer	Nej	100	Max antal kontakter att returnera. Måste vara 1–500.
sortByField	string	Nej	(ingen)	Sortera kontakter fallande efter detta fält.
status	string	Nej	(ingen)	Filtrera på kontaktstatus. status=1 är standard lead poll, inklusive positiva meddelandeflöde smarta leads.

Tillåtna sortByField-värden:

Värde	Sorterar efter
createdAt	Kontaktens skapelsedatum. När denna sortering begärs (och status utelämnas eller 1), slås sena smarta leads från de senaste 14 dagarna ihop och sidan sorteras om efter max(createdAt, leadCapturedAt) så att de visas utan att ersätta nyare webbkontakter.
updatedAt	Senaste uppdateringsdatum
lastConversationDate	Senaste konversationsdatum
leadCapturedAt	När kontakten blev en smart lead (faller tillbaka till updatedAt för historiska rader)
companyUsers.lastConversationDate	Äldre alias för lastConversationDate (Zapier-kompatibilitet)

Sortering är alltid fallande (nyast/högst först). Om utelämnad används MongoDB:s naturliga ordning.

Svar

Lyckat (200 OK)

{
  "data": [ /* array of contact objects */ ],
  "leadsCount": 42,
  "customerCount": 18
}

Fält	Typ	Beskrivning
data	array	Kontaktposter för ditt företag
leadsCount	number	Kontakter med status "1" eller null
customerCount	number	Kontakter med status "2"

leadsCount och customerCount speglar alla kontakter för företaget, inte bara den aktuella sidan.

Kontaktobjektfält

Varje post i data innehåller endast fälten nedan (känsliga/interna fält exkluderas):

Fält	Beskrivning
id	Zapier poll-identitet. Vanligtvis Mongo _id. Sena konverterande smarta leads (leadCapturedAt minst 1 timme efter createdAt, och på eller efter 2026-09-11) använder {mongoId}__sl så att New Contact kan triggas. Använd contactId för stabilt Mongo-id.
contactId	Stabilt Mongo _id. Ändras inte när id skrivs om för en sen smart lead.
linkedinUrl	LinkedIn-profil-URL om tillgänglig (översta linkedinUrl eller första linkedinProfiles[].url).
userId	Användaridentifierare
email	E-postadress
firstName	Förnamn
lastName	Efternamn
msisdn	Telefonnummer
company	Företagsnamn (kontaktens arbetsgivare, om det fångats)
city, state, street, zip	Adressfält
status	Kontaktens livscykelstatus (se nedan). Positiva meddelandeflöde smarta leads använder "1" som webbformulärleads.
leadSentiment	"positive" eller "negative" när ett meddelandeflödesvar klassificerats; annars utelämnat
leadCapturedAt	ISO-8601-tidpunkt då kontakten blev en positiv smart lead (faller tillbaka till updatedAt om saknas)
tags	Lösta kontakttaggar { id, name, systemKind? }[] (inkluderar Auto: Positive Lead / Auto: Negative Lead)
brandId	Varumärkesidentifierare
operatorId	Företags-/operatörsidentifierare
createdAt	ISO-8601-skapelsetidstämpel
updatedAt	ISO-8601 senaste uppdatering
lastConversationDate	ISO-8601 datum för senaste konversation
acceptedCommunication	Om kontakten accepterat kommunikation
acceptedPrivacy	Om kontakten accepterat sekretessvillkor
inviterUser	Vem som refererade denna kontakt (objekt)
rewardFlows	Flöden där belöningar tjänades
promosPresented	Kampanjer som visats för kontakten
promosRedeemed	Kampanjer som lösts in
answeredSurveyQuestions	Enkätssvar
usersReferred	Användare som denna kontakt har refererat
referralLinks	Detaljer om referenslänk
visitList	Besöks-/sessionshistorik (enhet, UTM, geo, etc.)
textFields	Anpassade textfält fångade i flöden

Fält kan vara null eller saknas om de inte samlats in för den kontakten.

Kontaktstatusvärden

Status	Betydelse
"1"	Lead (inkluderar positiva meddelandeflöde smarta leads)
"2"	Kund
"3"	Förlorad
"4"	Konverterad
null	Behandlas som Lead i antal

Nästlade objektformer

inviterUser

{
  "id": 123,
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]"
}

rewardFlows / promos

{ "id": "...", "title": "Summer promo" }

referralLinks

{
  "key": "...",
  "campaignId": 1,
  "campaignName": "...",
  "flowVariantId": 1,
  "url": "https://...",
  "share": true
}

visitList — inkluderar browser, os, deviceType, country, region, city, UTM-fält (utmSource, utmMedium, utmCampaign, etc.), referrer, landingPage, userAgent, ip.

answeredSurveyQuestions — inkluderar fråga/svar-text, översättningar, belöningsinfo och tidsstämplar.

textFields — anpassade flödesfält: flowId, flowName, variantId, variantName, key, value.

Felsvar

Alla fel returnerar JSON med ett error-fält. Vissa inkluderar ett hint.

HTTP-status	Villkor	Exempel på body
401	Saknad token-header	{ "error": "Missing token header" }
401	Ogiltig/återkallad nyckel, eller sk_/pk_-nyckel använd	{ "error": "Invalid or revoked token", "hint": "You can create a valid token from the Integration Dashboard." }
403	Giltig nyckel men inget operatorId-anspråk	{ "error": "Unauthorized" }
422	limit > 500	{ "error": "limit must not exceed 500" }
422	Ogiltig sortByField	{ "error": "Invalid sortByField value" }
422	Ogiltig status	{ "error": "Invalid status value" }
404	Fel sökväg eller metod	Not Found (plain text)

Exempelförfrågningar

Enkel — hämta upp till 100 kontakter:

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact"

Hämta 25 kontakter, sorterade efter senaste konversation:

curl -s \
  -H "token: YOUR_API_KEY" \
  "https://api.smoc.ai/api/company/mongocontact?limit=25&sortByField=lastConversationDate"

Hämta standardleads (webbformulär och positiva meddelandeflöde smarta leads):

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

Exempel på trunkerat svar:

{
  "data": [
    {
      "id": "665a1b2c3d4e5f6789012345",
      "email": "[email protected]",
      "firstName": "Alex",
      "lastName": "Smith",
      "msisdn": "+4712345678",
      "status": "2",
      "operatorId": "10",
      "createdAt": "2025-03-15T10:22:00.000Z",
      "lastConversationDate": "2025-06-01T14:30:00.000Z",
      "visitList": [
        {
          "deviceType": "mobile",
          "browser": "Chrome",
          "country": "NO",
          "utmSource": "google"
        }
      ]
    }
  ],
  "leadsCount": 120,
  "customerCount": 45
}

Zapier-integration

SMOC tillhandahåller en Zapier-app som använder samma endpoint. Typiskt flöde:

1. Få tillgång via Zapier-inbjudningslänken (länkad från Console → Inställningar → Integrationer → Zapier).
2. Generera en API-nyckel i Console.
3. I Zapier: My Apps → Custom Integrations → Add Connection och klistra in nyckeln när du uppmanas ange token.
4. Skapa en Zap med trigger SMOC → New Contact.

Zapier-triggern pollar detta endpoint och behandlar returnerade kontakter som nya när de dyker upp. New Contact använder id. Sena konverterande smarta leads (importerade prospekt som senare får leadCapturedAt) får nu ett stabilt {contactId}__sl-id så att befintlig New Contact-Zap kan triggas en gång. contactId förblir Mongo-id för CRM-mappning. Detta gäller för alla företag; endast fångster på eller efter 2026-09-11 skrivs om (tillfälligt tills en dedikerad New Smart Lead-trigger finns). Föredra HubSpot Create or Update Contact på e-post för att undvika dubbletter om prospektet redan synkats. Se Zapier eGuide för steg-för-steg-setup.

Begränsningar och designanteckningar

• Kundnycklar är skrivskyddade — mongocontact skriver inte. REST v2-verktyg för ändringar är endast för superadmin.
• Ingen offset/cursor-paginering — använd limit (max 500). För att synka alla kontakter, sortera konsekvent och spåra sedda ID:n på klientsidan, eller använd Zapiers pollingmodell.
• Automatisk avgränsning — API-nyckeln avgör företaget; det finns ingen multi-tenant override-parameter.
• Fält med begränsad projektion — endast ovanstående fält returneras; interna databasfält tas bort.
• Bakåtkompatibilitet — endpoint-sökvägen och companyUsers.lastConversationDate-sorteringsaliaset finns för bakåtkompatibilitet med det ursprungliga API:et och Zapier-appen.

Relaterat: MCP (AI-klienter)

Samma API-worker exponerar även MCP på https://api.smoc.ai/mcp och REST v2 på POST /api/v2/{toolName} med rikare kontaktverktyg (contacts_search, contacts_get, contacts_get_stats, etc.). Se MCP eGuide och REST v2-referensen.

För en produktöversikt av alla integrationsvägar, se smoc.ai/integrations.

Snabbreferens

Post	Värde
Endpoint	GET /api/company/mongocontact
Auth-header	token: <api-key>
Content type	application/json
Max sidstorlek	500
Standard sidstorlek	100
Företagsavgränsning	Från API-nyckel (operatorId-anspråk)
Nyckelskapande	Console → Inställningar → Integrationer → API

Se även

• REST v2 API-referens — varje POST /api/v2/{toolName}-anrop
• Ansluta SMOC med REST API
• Public Contacts API
• MCP för Claude, Cursor och VS Code