SMOC Public Contacts API — Integrationsvejledning

Guide til SMOC Public Contacts API — et skrivebeskyttet REST-endpoint til at liste kontakter og samlede tællinger for din virksomhed. Brug det fra egne integrationer, synkroniseringsjobs eller sammen med Zapier-appen.

Oversigt

SMOC Public API giver tredjepartssystemer mulighed for at læse kontakter for én virksomhed. Det hostes på Cloudflare Workers og afgrænses automatisk til den virksomhed, der er knyttet til din API-nøgle.

Hvad det kan i dag:

• Liste kontakter for din virksomhed (op til 500 pr. forespørgsel)
• Returnere samlede tællinger af leads og kunder
• Afgrænse data automatisk til virksomheden, der er knyttet til din API-nøgle

Hvad det ikke kan:

• Oprette, opdatere eller slette kontakter
• Paginere med cursor eller offset (kun et limit loft)
• Forespørge på tværs af flere virksomheder med én nøgle

Denne Zapier/compat-kontrakt forbliver uændret. Det eneste contacts-endpoint for denne kontrakt er:

GET /api/company/mongocontact

Mere avanceret kontakt-søgning er tillægsfunktionalitet: POST /api/v2/contacts_search. Flyt ikke Zapier væk fra mongocontact.

For opsætning i Console, autentificering og funktionsoversigt, start med REST API-forbindelsesguiden.

Hent din API-nøgle

Alle SMOC data-integrationer bruger samme Console-tokenmønster som Zapier og MCP:

1. Log ind på SMOC Console.
2. Gå til Indstillinger → Integrationer → API (brug Integrationer → Zapier til Zapier-specifik opsætning).
3. Navngiv eventuelt nøglen og angiv udløb, klik derefter på Generer ny API-nøgle.
4. Kopiér nøglen med det samme — den vises kun én gang og kan ikke hentes senere.

At generere en ny nøgle deaktiverer ikke eksisterende nøgler. Udstedte nøgler vises på samme side — tilbagekald ubrugte nøgler der, når du skal rotere legitimationsoplysninger.

Hver nøgle er bundet til én virksomhed. Nøglen bærer et operatorId-claim svarende til virksomhedens ID. API'et bruger dette til at afgrænse alle kontaktdata — du kan ikke angive et andet virksomheds-ID i forespørgslen.

Base-URL'er

Miljø	Base-URL
Produktion	https://api.smoc.ai

Fuld endpoint-eksempel:

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

Autentificering

Send din API-nøgle i et brugerdefineret HTTP-header med navnet token:

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

API'et verificerer nøglen og læser operatorId-claim for at afgøre, hvilke kontakter for virksomheden der skal returneres. Du skal ikke sende virksomheds-ID i URL eller query string.

Brug ikke:

• Authorization: Bearer … — denne header accepteres ikke af dette endpoint (selvom Console-siden "API-adgang" måske viser det). Brug token-header i integrationer, indtil der er produktsupport for Bearer.
• Clerk secret keys (sk_…) eller publishable keys (pk_…) — disse afvises med 401 Invalid token type.

Forespørgsel

Metode: Kun GET. Andre metoder (fx POST) returnerer 404 Not Found.

Query-parametre

Parameter	Type	Påkrævet	Standard	Beskrivelse
limit	integer	Nej	100	Maks antal kontakter der returneres. Skal være 1–500.
sortByField	string	Nej	(ingen)	Sortér kontakter faldende efter dette felt.
status	string	Nej	(ingen)	Filtrér efter kontaktstatus. status=1 er standard lead poll, inkl. positive beskedflow smart leads.

Tilladte sortByField-værdier:

Værdi	Sorterer efter
createdAt	Kontaktens oprettelsesdato. Når denne sortering vælges (og status udelades eller 1), flettes nylige sene smart leads fra de sidste 14 dage ind, og siden sorteres igen efter max(createdAt, leadCapturedAt), så de vises uden at fortrænge nyere webkontakter.
updatedAt	Sidste opdateringsdato
lastConversationDate	Sidste samtaledato
leadCapturedAt	Hvornår kontakten blev smart lead (falder tilbage til updatedAt for historiske rækker)
companyUsers.lastConversationDate	Legacy-alias for lastConversationDate (Zapier-kompatibilitet)

Sortering er altid faldende (nyeste/højeste først). Hvis udeladt, bruges MongoDB's naturlige rækkefølge.

Svar

Succes (200 OK)

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

Felt	Type	Beskrivelse
data	array	Kontaktposter for din virksomhed
leadsCount	number	Kontakter med status "1" eller null
customerCount	number	Kontakter med status "2"

leadsCount og customerCount afspejler alle kontakter for virksomheden, ikke kun den aktuelle side.

Kontaktobjekt-felter

Hvert element i data indeholder kun nedenstående felter (følsomme/interne felter er udeladt):

Felt	Beskrivelse
id	Zapier poll-identitet. Normalt Mongo _id. Sene konverterede smart leads (leadCapturedAt mindst 1 time efter createdAt, og på eller efter 2026-09-11) bruger {mongoId}__sl, så New Contact kan udløses. Brug contactId for stabil Mongo-id.
contactId	Stabil Mongo _id. Ændres ikke, når id omskrives for et sent smart lead.
linkedinUrl	LinkedIn-profil-URL hvis tilgængelig (øverste linkedinUrl eller første linkedinProfiles[].url).
userId	Bruger-ID
email	E-mailadresse
firstName	Fornavn
lastName	Efternavn
msisdn	Telefonnummer
company	Virksomhedsnavn (kontaktens arbejdsgiver, hvis opfanget)
city, state, street, zip	Adressefelter
status	Kontaktens livscyklusstatus (se nedenfor). Positive beskedflow smart leads bruger "1" ligesom webformular-leads.
leadSentiment	"positive" eller "negative" når et beskedflow-svar blev klassificeret; udeladt ellers
leadCapturedAt	ISO-8601 tidspunkt hvor kontakten blev positivt smart lead (falder tilbage til updatedAt hvis mangler)
tags	Opløste kontakt-tags { id, name, systemKind? }[] (inkl. Auto: Positive Lead / Auto: Negative Lead)
brandId	Brand-ID
operatorId	Virksomheds-/operatør-ID
createdAt	ISO-8601 oprettelsestidspunkt
updatedAt	ISO-8601 sidste opdateringstidspunkt
lastConversationDate	ISO-8601 dato for sidste samtale
acceptedCommunication	Om kontakten har accepteret kommunikation
acceptedPrivacy	Om kontakten har accepteret privatlivsvilkår
inviterUser	Hvem der har henvist denne kontakt (objekt)
rewardFlows	Flows hvor belønninger blev optjent
promosPresented	Kampagner vist til kontakten
promosRedeemed	Kampagner indløst
answeredSurveyQuestions	Surveybesvarelser
usersReferred	Brugere denne kontakt har henvist
referralLinks	Detaljer om henvisningslink
visitList	Besøgs-/sessionshistorik (enhed, UTM, geo osv.)
textFields	Tilpassede tekstfelter opfanget i flows

Felter kan være null eller mangle, hvis de ikke er indsamlet for kontakten.

Kontaktstatus-værdier

Status	Betydning
"1"	Lead (inkl. positive beskedflow smart leads)
"2"	Kunde
"3"	Tabt
"4"	Konverteret
null	Tælles som Lead

Indlejrede objekt-formater

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 — inkluderer browser, os, deviceType, country, region, city, UTM-felter (utmSource, utmMedium, utmCampaign osv.), referrer, landingPage, userAgent, ip.

answeredSurveyQuestions — inkluderer spørgsmål/svar-tekst, oversættelser, belønningsinfo og tidsstempler.

textFields — tilpassede flowfelter: flowId, flowName, variantId, variantName, key, value.

Fejlsvar

Alle fejl returnerer JSON med et error-felt. Nogle inkluderer et hint.

HTTP-status	Betingelse	Eksempel-body
401	Manglende token-header	{ "error": "Missing token header" }
401	Ugyldig/tilbagekaldt nøgle, eller sk_/pk_-nøgle brugt	{ "error": "Invalid or revoked token", "hint": "You can create a valid token from the Integration Dashboard." }
403	Gyldig nøgle men intet operatorId-claim	{ "error": "Unauthorized" }
422	limit > 500	{ "error": "limit must not exceed 500" }
422	Ugyldig sortByField	{ "error": "Invalid sortByField value" }
422	Ugyldig status	{ "error": "Invalid status value" }
404	Forkert sti eller metode	Not Found (plain text)

Eksempel-forespørgsler

Basis — hent op til 100 kontakter:

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

Hent 25 kontakter, sorteret efter sidste samtale:

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

Hent standard leads (webformular og positive beskedflow smart leads):

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

Eksempel på trunkeret 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 tilbyder en Zapier-app, der bruger dette samme endpoint. Typisk flow:

1. Få adgang via Zapier-invite-linket (linket fra Console → Indstillinger → Integrationer → Zapier).
2. Generér en API-nøgle i Console.
3. I Zapier: Mine apps → Custom Integrations → Tilføj forbindelse og indsæt nøglen, når du bliver bedt om et token.
4. Opret et Zap med triggeren SMOC → New Contact.

Zapier-triggeren poller dette endpoint og behandler returnerede kontakter som nye, når de vises. New Contact bruger id. Sene konverterede smart leads (importerede prospects der senere får leadCapturedAt) får nu et stabilt {contactId}__sl-id, så det eksisterende New Contact Zap kun udløses én gang. contactId forbliver Mongo-id til CRM-mapping. Dette gælder for alle virksomheder; kun oprettelser på eller efter 2026-09-11 omskrives (midlertidigt indtil dedikeret New Smart Lead-trigger findes). Foretræk HubSpot Create or Update Contact på e-mail for at undgå dubletter, hvis prospect allerede var synkroniseret. Se Zapier eGuide for trin-for-trin opsætning.

Begrænsninger og designnoter

• Kundenøgler er skrivebeskyttede — mongocontact skriver ikke. REST v2-muterende værktøjer er kun for superadmin.
• Ingen offset/cursor-paginering — brug limit (maks 500). For at synkronisere alle kontakter, sorter konsekvent og track sete ID'er på klientsiden, eller brug Zapiers polling-model.
• Automatisk afgrænsning — API-nøglen bestemmer virksomheden; der er ingen multi-tenant override-parameter.
• Begrænsede felter — kun de ovennævnte felter returneres; interne databasefelter fjernes.
• Legacy-kompatibilitet — endpoint-stien og companyUsers.lastConversationDate-sorteringsalias eksisterer for bagudkompatibilitet med det oprindelige API og Zapier-app.

Relateret: MCP (AI-klienter)

Samme API-worker udstiller også MCP på https://api.smoc.ai/mcp og REST v2 på POST /api/v2/{toolName} med mere avancerede kontaktværktøjer (contacts_search, contacts_get, contacts_get_stats osv.). Se MCP eGuide og REST v2 reference.

For et produkt-overblik over alle integrationsveje, se smoc.ai/integrations.

Hurtig reference

Punkt	Værdi
Endpoint	GET /api/company/mongocontact
Auth-header	token: <api-key>
Content-type	application/json
Maks side-størrelse	500
Standard side-størrelse	100
Virksomhedsafgrænsning	Fra API-nøgle (operatorId-claim)
Nøgleoprettelse	Console → Indstillinger → Integrationer → API

Se også

• REST v2 API reference — alle POST /api/v2/{toolName}-kald
• Forbind SMOC med REST API
• Public Contacts API
• MCP til Claude, Cursor og VS Code