SMOC Public Contacts API — Integrasjonsveiledning

Guide til SMOC Public Contacts API — et skrivebeskyttet REST-endepunkt for å liste kontakter og samlede tellinger for din bedrift. Bruk det fra egendefinerte integrasjoner, synkroniseringsjobber eller sammen med Zapier-appen.

Oversikt

SMOC Public API lar tredjepartssystemer lese kontakter for én enkelt bedrift. Det er hostet på Cloudflare Workers og avgrenses automatisk til bedriften som er knyttet til din API-nøkkel.

Dette gjør det i dag:

• Lister kontakter for din bedrift (opptil 500 per forespørsel)
• Returnerer samlede tellinger av leads og kunder
• Avgrenser data automatisk til bedriften som er knyttet til din API-nøkkel

Dette gjør det ikke:

• Opprette, oppdatere eller slette kontakter
• Paginere med markører eller offset (kun en limit-grense)
• Spørre på tvers av flere bedrifter med én nøkkel

Denne Zapier/compat-kontrakten forblir uendret. Det eneste kontakt-endepunktet for denne kontrakten er:

GET /api/company/mongocontact

Rikere kontaktsøk er tillegg: POST /api/v2/contacts_search. Ikke migrer Zapier bort fra mongocontact.

For oppsett i Console, autentisering og funksjonsoversikt, start med REST API-tilkoblingsguiden.

Hent din API-nøkkel

Alle SMOC-dataintegrasjoner bruker samme Console-tokenmønster som Zapier og MCP:

1. Logg inn i SMOC Console.
2. Gå til Innstillinger → Integrasjoner → API (bruk Integrasjoner → Zapier for Zapier-spesifikt oppsett).
3. Gi eventuelt nøkkelen et navn og angi utløpsdato, klikk deretter Generer ny API-nøkkel.
4. Kopier nøkkelen umiddelbart — den vises kun én gang og kan ikke hentes senere.

Å generere en ny nøkkel opphever ikke eksisterende nøkler. Utstedte nøkler listes på samme side — opphev ubrukte nøkler der når du trenger å rotere legitimasjon.

Hver nøkkel er bundet til én bedrift. Nøkkelen har et operatorId-krav lik bedriftens ID. API-et bruker dette for å avgrense alle kontaktdata — du kan ikke sende en annen bedrifts-ID i forespørselen.

Base-URLer

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

Fullt endepunkteksempel:

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

Autentisering

Send din API-nøkkel i en egendefinert HTTP-header kalt token:

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

API-et verifiserer nøkkelen og leser operatorId-kravet for å avgjøre hvilke kontakter som skal returneres for bedriften. Du skal ikke sende en bedrifts-ID i URL eller spørring.

Ikke bruk:

• Authorization: Bearer … — denne headeren aksepteres ikke av dette endepunktet (selv om Console-siden "API Access" kanskje viser det nå). Bruk token-headeren i integrasjoner til produktsupport for Bearer er lagt til.
• Clerk secret keys (sk_…) eller publishable keys (pk_…) — disse avvises med 401 Invalid token type.

Forespørsel

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

Spørringsparametere

Parameter	Type	Påkrevd	Standard	Beskrivelse
limit	integer	Nei	100	Maks antall kontakter som returneres. Må være 1–500.
sortByField	string	Nei	(ingen)	Sorter kontakter synkende etter dette feltet.
status	string	Nei	(ingen)	Filtrer etter kontaktstatus. status=1 er standard lead-poll, inkludert positive meldingsflyt smart-leads.

Tillatte sortByField-verdier:

Verdi	Sorterer etter
createdAt	Kontaktens opprettelsesdato. Når denne sorteringen er forespurt (og status er utelatt eller 1), flettes nylige sene smart-leads fra de siste 14 dagene inn og siden sorteres på nytt etter max(createdAt, leadCapturedAt) slik at de vises uten å fortrenge nyere nett-kontakter.
updatedAt	Siste oppdateringsdato
lastConversationDate	Siste samtaledato
leadCapturedAt	Når kontakten ble en smart lead (faller tilbake til updatedAt for historiske rader)
companyUsers.lastConversationDate	Legacy-alias for lastConversationDate (Zapier-kompatibilitet)

Sortering er alltid synkende (nyeste/høyeste først). Hvis utelatt, brukes MongoDBs naturlige rekkefølge.

Svar

Suksess (200 OK)

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

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

leadsCount og customerCount reflekterer alle kontakter for bedriften, ikke bare den nåværende siden.

Kontaktobjekt-felter

Hvert element i data inkluderer kun feltene under (sensitive/interne felter er utelatt):

Felt	Beskrivelse
id	Zapier poll-identitet. Vanligvis Mongo _id. Sene smart-leads (leadCapturedAt minst 1 time etter createdAt, og på eller etter 2026-09-11) bruker {mongoId}__sl slik at New Contact kan utløses. Bruk contactId for stabil Mongo-id.
contactId	Stabil Mongo _id. Endres ikke når id omskrives for en sen smart lead.
linkedinUrl	LinkedIn-profil-URL når tilstede (toppnivå linkedinUrl eller første linkedinProfiles[].url).
userId	Brukeridentifikator
email	E-postadresse
firstName	Fornavn
lastName	Etternavn
msisdn	Telefonnummer
company	Firmanavn (kontaktens arbeidsgiver, hvis registrert)
city, state, street, zip	Adressefelter
status	Kontaktens livssyklusstatus (se under). Positive meldingsflyt smart-leads bruker "1" som nett-skjema-leads.
leadSentiment	"positive" eller "negative" når en meldingsflyt-replikk ble klassifisert; utelatt ellers
leadCapturedAt	ISO-8601-tid da kontakten ble en positiv smart lead (faller tilbake til updatedAt hvis mangler)
tags	Løste kontakttagger { id, name, systemKind? }[] (inkluderer Auto: Positive Lead / Auto: Negative Lead)
brandId	Merkeidentifikator
operatorId	Bedrifts-/operatøridentifikator
createdAt	ISO-8601 opprettelsestidspunkt
updatedAt	ISO-8601 siste oppdateringstidspunkt
lastConversationDate	ISO-8601 dato for siste samtale
acceptedCommunication	Om kontakten har godtatt kommunikasjon
acceptedPrivacy	Om kontakten har godtatt personvernbetingelser
inviterUser	Hvem som har henvist denne kontakten (objekt)
rewardFlows	Flyter hvor belønninger ble opptjent
promosPresented	Kampanjer vist til kontakten
promosRedeemed	Kampanjer innløst
answeredSurveyQuestions	Undersøkelsessvar
usersReferred	Brukere denne kontakten har henvist
referralLinks	Detaljer om henvisningslenke
visitList	Besøks-/øktshistorikk (enhet, UTM, geo, osv.)
textFields	Egendefinerte tekstfelt fanget i flyter

Felt kan være null eller fraværende hvis ikke innhentet for den kontakten.

Kontaktstatus-verdier

Status	Betydning
"1"	Lead (inkluderer positive meldingsflyt smart-leads)
"2"	Kunde
"3"	Tapt
"4"	Konvertert
null	Behandles som Lead i tellinger

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

answeredSurveyQuestions — inkluderer spørsmål/svar-tekst, oversettelser, belønningsinformasjon og tidsstempler.

textFields — egendefinerte flytfelt: flowId, flowName, variantId, variantName, key, value.

Feilsvar

Alle feil returnerer JSON med et error-felt. Noen inkluderer et hint.

HTTP-status	Tilstand	Eksempel på respons
401	Mangler token-header	{ "error": "Missing token header" }
401	Ugyldig/opphevet nøkkel, eller sk_/pk_-nøkkel brukt	{ "error": "Invalid or revoked token", "hint": "You can create a valid token from the Integration Dashboard." }
403	Gyldig nøkkel men mangler operatorId-krav	{ "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	Feil sti eller metode	Not Found (ren tekst)

Eksempelforespørsler

Grunnleggende — hent opptil 100 kontakter:

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

Hent 25 kontakter, sortert etter siste samtale:

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

Hent standard leads (nett-skjema og positive meldingsflyt smart-leads):

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

Eksempel på avkortet 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-integrasjon

SMOC tilbyr en Zapier-app som bruker dette samme endepunktet. Typisk flyt:

1. Få tilgang via Zapier-invitasjonslenken (lenket fra Console → Innstillinger → Integrasjoner → Zapier).
2. Generer en API-nøkkel i Console.
3. I Zapier: Mine apper → Egendefinerte integrasjoner → Legg til tilkobling og lim inn nøkkelen når du blir bedt om token.
4. Opprett en Zap med utløseren SMOC → Ny kontakt.

Zapier-utløseren spør dette endepunktet og behandler returnerte kontakter som nye når de dukker opp. Ny kontakt bruker id som nøkkel. Sene smart-leads (importerte prospekter som senere får leadCapturedAt) får nå en stabil {contactId}__sl-id slik at eksisterende Ny kontakt-Zap kan utløses én gang. contactId forblir Mongo-id for CRM-kartlegging. Dette gjelder for alle bedrifter; kun innsamlinger på eller etter 2026-09-11 omskrives (midlertidig til en dedikert Ny smart lead-utløser finnes). Foretrekk HubSpot Opprett eller oppdater kontakt på e-post for å unngå duplikater hvis prospektet allerede var synkronisert. Se Zapier eGuide for steg-for-steg-oppsett.

Begrensninger og designnotater

• Kundenøkler er skrivebeskyttet — mongocontact skriver ikke. REST v2-verktøy for endringer er kun for superadministrator.
• Ingen offset/markør-paginering — bruk limit (maks 500). For å synkronisere alle kontakter, sorter konsekvent og spor sett ID-er på klientsiden, eller bruk Zapiers polling-modell.
• Automatisk avgrensning — API-nøkkelen bestemmer bedriften; det finnes ingen multi-tenant-parameter.
• Projeksjonsbegrensede felter — kun feltene over returneres; interne databasefelt fjernes.
• Bakoverkompatibilitet — endepunktstien og companyUsers.lastConversationDate-sorteringsaliaset finnes for bakoverkompatibilitet med det opprinnelige API-et og Zapier-appen.

Relatert: MCP (AI-klienter)

Den samme API-worker eksponerer også MCP på https://api.smoc.ai/mcp og REST v2 på POST /api/v2/{toolName} med rikere kontaktverktøy (contacts_search, contacts_get, contacts_get_stats, osv.). Se MCP eGuide og REST v2-referansen.

For en produktoppsummering av alle integrasjonsveier, se smoc.ai/integrasjoner.

Hurtigreferanse

Element	Verdi
Endepunkt	GET /api/company/mongocontact
Auth-header	token: <api-key>
Content type	application/json
Maks sidestørrelse	500
Standard sidestørrelse	100
Bedriftsavgrensning	Fra API-nøkkel (operatorId-krav)
Nøkkelopprettelse	Console → Innstillinger → Integrasjoner → API

Se også

• REST v2 API-referanse — hver POST /api/v2/{toolName}-kall
• Koble SMOC til REST API
• Public Contacts API
• MCP for Claude, Cursor og VS Code