SMOC Public Contacts API — Integraatio-opas

Opas SMOC Public Contacts API:iin — lukuoikeudellinen REST-päätepiste, jolla voit listata kontakteja ja hakea aggregoituja määriä yrityksellesi. Käytä tätä omissa integraatioissa, synkronointitöissä tai yhdessä Zapier-sovelluksen kanssa.

Yleiskatsaus

SMOC Public API mahdollistaa kolmansien osapuolten järjestelmien lukea kontaktit yhdelle yritykselle. Se toimii Cloudflare Workers -palvelussa ja rajaa tiedot automaattisesti API-avaimeesi liitettyyn yritykseen.

Tämänhetkiset ominaisuudet:

• Listaa yrityksesi kontaktit (enintään 500 per pyyntö)
• Palauttaa liidien ja asiakkaiden kokonaismäärät
• Rajaa tiedot automaattisesti API-avaimeesi liitettyyn yritykseen

Mitä tämä ei tee:

• Luo, päivitä tai poista kontakteja
• Sivuuta kursoreilla tai offseteilla (vain limit raja)
• Kysy usean yrityksen tietoja yhdellä avaimella

Tämä Zapier/compat-sopimus pysyy ennallaan. Sopimuksen ainoa contacts-päätepiste on:

GET /api/company/mongocontact

Laajempi kontaktihaku on lisäominaisuus: POST /api/v2/contacts_search. Älä siirrä Zapieria pois mongocontactista.

Konsolin käyttöönottoon, autentikointiin ja toimintoihin tutustu REST API -yhteysoppaaseen.

Hanki API-avaimesi

Kaikki SMOC:n data-integraatiot käyttävät samaa Konsolin tunnusmallia kuin Zapier ja MCP:

1. Kirjaudu sisään SMOC Consoleen.
2. Siirry kohtaan Asetukset → Integraatiot → API (käytä Integraatiot → Zapier Zapier-kohtaiseen asetukseen).
3. Anna avaimelle halutessasi nimi ja voimassaoloaika, sitten klikkaa Luo uusi API-avain.
4. Kopioi avain heti — se näytetään vain kerran eikä sitä voi hakea myöhemmin uudelleen.

Uuden avaimen luominen ei poista aiempia avaimia käytöstä. Myönnetyt avaimet näkyvät samalla sivulla — poista käyttämättömät avaimet sieltä, kun haluat kierrättää tunnuksia.

Jokainen avain on sidottu yhteen yritykseen. Avaimeen tallennetaan operatorId-väite, joka vastaa yrityksen ID:tä. API käyttää tätä rajatakseen kaikki kontaktitiedot — et voi välittää toista yritys-ID:tä pyynnössä.

Perus-URL:t

Ympäristö	Perus-URL
Tuotanto	https://api.smoc.ai

Täydellinen päätepiste-esimerkki:

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

Autentikointi

Lähetä API-avaimesi mukautetussa HTTP-otsikossa nimeltä token:

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

API tarkistaa avaimen ja lukee operatorId-väitteen määrittääkseen, minkä yrityksen kontaktit palautetaan. Et lähetä yritys-ID:tä URL:ssa tai kyselymerkkijonossa.

Älä käytä:

• Authorization: Bearer … — tätä otsikkoa ei hyväksytä tässä päätepisteessä (vaikka Konsolin "API Access" -sivu saattaa näyttää toisin). Käytä token-otsikkoa integraatioissa, kunnes Bearer-tuki lisätään tuotteeseen.
• Clerk secret keys (sk_…) tai publishable keys (pk_…) — nämä hylätään 401 Invalid token type-viestillä.

Pyyntö

Metodi: Vain GET. Muut metodit (esim. POST) palauttavat 404 Not Found.

Kyselyparametrit

Parametri	Tyyppi	Pakollinen	Oletus	Kuvaus
limit	kokonaisluku	Ei	100	Palautettavien kontaktien enimmäismäärä. Voi olla 1–500.
sortByField	merkkijono	Ei	(ei oletusta)	Järjestä kontaktit laskevasti tämän kentän mukaan.
status	merkkijono	Ei	(ei oletusta)	Suodata kontaktin statuksen mukaan. status=1 on vakio liidien haku, mukaan lukien positiiviset viestivirran smart leadit.

Sallitut sortByField-arvot:

Arvo	Järjestää
createdAt	Kontaktin luontipäivämäärä. Kun tämä järjestys pyydetään (ja status puuttuu tai 1), viimeisen 14 päivän myöhäiset smart leadit yhdistetään ja sivu järjestetään uudelleen max(createdAt, leadCapturedAt):n mukaan, jotta ne näkyvät ilman että uudemmat verkkokontaktit siirtyvät.
updatedAt	Viimeisin päivityspäivä
lastConversationDate	Viimeisin keskustelupäivä
leadCapturedAt	Milloin kontaktista tuli smart lead (palaa updatedAt:een historiallisille riveille)
companyUsers.lastConversationDate	Perinteinen alias lastConversationDate:lle (Zapier-yhteensopivuus)

Järjestys on aina laskeva (uusin/suurin ensin). Jos jätetään pois, käytetään MongoDB:n luonnollista järjestystä.

Vastaus

Onnistunut (200 OK)

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

Kenttä	Tyyppi	Kuvaus
data	taulukko	Yrityksesi kontaktitiedot
leadsCount	numero	Kontaktit, joiden status on "1" tai null
customerCount	numero	Kontaktit, joiden status on "2"

leadsCount ja customerCount kuvaavat kaikkia yrityksen kontakteja, eivät vain nykyistä sivua.

Kontaktin kentät

Jokainen data:n kohde sisältää vain alla olevat kentät (herkät/sisäiset kentät on jätetty pois):

Kenttä	Kuvaus
id	Zapier-pollin tunniste. Yleensä Mongo _id. Myöhään konvertoituvat smart leadit (leadCapturedAt vähintään 1 tunti createdAt:n jälkeen ja 11.9.2026 tai sen jälkeen) käyttävät {mongoId}__sl, jotta New Contact voi laukaista. Käytä contactId vakiona Mongo id:nä.
contactId	Vakaa Mongo _id. Ei muutu, kun id kirjoitetaan uudelleen myöhäiselle smart leadille.
linkedinUrl	LinkedIn-profiilin URL, jos saatavilla (ylätason linkedinUrl tai ensimmäinen linkedinProfiles[].url).
userId	Käyttäjätunniste
email	Sähköpostiosoite
firstName	Etunimi
lastName	Sukunimi
msisdn	Puhelinnumero
company	Yrityksen nimi (kontaktin työnantaja, jos tallennettu)
city, state, street, zip	Osoitekentät
status	Kontaktin elinkaaren status (katso alla). Positiiviset viestivirran smart leadit käyttävät "1" kuten verkkolomakkeen liidit.
leadSentiment	"positive" tai "negative", kun viestivirran vastaus on luokiteltu; muuten puuttuu
leadCapturedAt	ISO-8601-aika, jolloin kontaktista tuli positiivinen smart lead (palaa updatedAt:een, jos puuttuu)
tags	Ratkaistut kontaktitagit { id, name, systemKind? }[] (sisältää Auto: Positive Lead / Auto: Negative Lead)
brandId	Brändin tunniste
operatorId	Yrityksen/operaattorin tunniste
createdAt	ISO-8601-luontiaikaleima
updatedAt	ISO-8601-viimeisin päivitysaika
lastConversationDate	ISO-8601-viimeisin keskustelupäivä
acceptedCommunication	Onko kontakti hyväksynyt viestinnän
acceptedPrivacy	Onko kontakti hyväksynyt tietosuojan ehdot
inviterUser	Kuka suositteli tätä kontaktia (objekti)
rewardFlows	Virrat, joissa palkintoja ansaittiin
promosPresented	Kontaktin näkemät kampanjat
promosRedeemed	Lunastetut kampanjat
answeredSurveyQuestions	Kyselyvastaukset
usersReferred	Käyttäjät, jotka tämä kontakti on suositellut
referralLinks	Suosituslinkin tiedot
visitList	Vierailu-/sessiohistoria (laite, UTM, sijainti jne.)
textFields	Mukautetut tekstikentät, jotka on kerätty virroissa

Kentät voivat olla null tai puuttua, jos niitä ei ole kerätty kyseiselle kontaktille.

Kontaktin status-arvot

Status	Merkitys
"1"	Liidi (sisältää positiiviset viestivirran smart leadit)
"2"	Asiakas
"3"	Menetetty
"4"	Konvertoitu
null	Lasketaan liidiksi

Sisäkkäisten objektien muodot

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 — sisältää browser, os, deviceType, country, region, city, UTM-kentät (utmSource, utmMedium, utmCampaign jne.), referrer, landingPage, userAgent, ip.

answeredSurveyQuestions — sisältää kysymys/vastaustekstin, käännökset, palkintotiedot ja aikaleimat.

textFields — mukautetut virtakentät: flowId, flowName, variantId, variantName, key, value.

Virhevastausten käsittely

Kaikki virheet palauttavat JSONin, jossa on error-kenttä. Joissain on myös hint.

HTTP-status	Ehto	Esimerkkirunko
401	token-otsikko puuttuu	{ "error": "Missing token header" }
401	Virheellinen/poistettu avain, tai sk_/pk_-avain käytetty	{ "error": "Invalid or revoked token", "hint": "You can create a valid token from the Integration Dashboard." }
403	Kelvollinen avain, mutta operatorId-väite puuttuu	{ "error": "Unauthorized" }
422	limit > 500	{ "error": "limit must not exceed 500" }
422	Virheellinen sortByField	{ "error": "Invalid sortByField value" }
422	Virheellinen status	{ "error": "Invalid status value" }
404	Väärä polku tai metodi	Not Found (plain text)

Esimerkkipyynnöt

Perus — hae enintään 100 kontaktia:

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

Hae 25 kontaktia, järjestetty viimeisimmän keskustelun mukaan:

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

Hae vakio-liidit (verkkolomake ja positiiviset viestivirran smart leadit):

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

Esimerkkivastaus (katkaistu):

{
  "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-integraatio

SMOC tarjoaa Zapier-sovelluksen, joka käyttää tätä samaa päätepistettä. Tyypillinen korttivirta:

1. Hanki pääsy Zapierin kutsulinkin kautta (Konsoli → Asetukset → Integraatiot → Zapier).
2. Luo API-avain Konsolissa.
3. Zapierissa: My Apps → Custom Integrations → Add Connection ja liitä avain, kun sitä pyydetään.
4. Luo Zap, jonka triggerinä on SMOC → New Contact.

Zapierin triggeri pollaa tätä päätepistettä ja käsittelee palautetut kontaktit uusina, kun ne ilmestyvät. New Contact perustuu id:ään. Myöhään konvertoituvat smart leadit (tuodut prospektit, jotka myöhemmin saavat leadCapturedAt:n) saavat nyt vakaan {contactId}__sl-id:n, jotta olemassa oleva New Contact Zap voi laukaista kerran. contactId pysyy Mongo id:nä CRM-kartoituksessa. Tämä koskee jokaista yritystä; vain 11.9.2026 tai sen jälkeen tallennetut tiedot kirjoitetaan uudelleen (väliaikainen, kunnes oma New Smart Lead -triggeri on olemassa). Suosi HubSpotin Create or Update Contact -toimintoa sähköpostilla, jotta vältät duplikaatit, jos prospekti on jo synkronoitu. Katso Zapier eGuide vaiheittaisiin ohjeisiin.

Rajoitukset ja suunnitteluhuomiot

• Asiakasavaimet ovat vain lukuoikeudella — mongocontact ei kirjoita. REST v2:n muokkaustyökalut ovat vain superadmin-käytössä.
• Ei offset-/kursori-sivutusta — käytä limit (max 500). Synkronoidaksesi kaikki kontaktit, järjestä johdonmukaisesti ja seuraa nähtyjä ID:itä asiakaspäässä, tai käytä Zapierin polling-mallia.
• Automaattinen rajaus — API-avain määrittää yrityksen; ei ole monivuokraaja-parametria.
• Rajatut kentät — vain yllä listatut kentät palautetaan; sisäiset tietokantakentät poistetaan.
• Perinteinen yhteensopivuus — päätepisteen polku ja companyUsers.lastConversationDate-järjestysalias ovat olemassa taaksepäin yhteensopivuuden vuoksi alkuperäisen API:n ja Zapier-sovelluksen kanssa.

Liittyvä: MCP (AI-asiakkaat)

Sama API worker tarjoaa myös MCP:n osoitteessa https://api.smoc.ai/mcp ja REST v2:n osoitteessa POST /api/v2/{toolName}, joissa on laajemmat kontaktityökalut (contacts_search, contacts_get, contacts_get_stats jne.). Katso MCP eGuide ja REST v2 -referenssi.

Kaikkien integraatiopolkujen tuotekatsauksen löydät osoitteesta smoc.ai/integrations.

Pikaviite

Kohta	Arvo
Päätepiste	GET /api/company/mongocontact
Auth header	token: <api-key>
Content type	application/json
Max sivukoko	500
Oletussivukoko	100
Yritysrajaus	API-avaimesta (operatorId-väite)
Avaimen luonti	Konsoli → Asetukset → Integraatiot → API

Katso myös

• REST v2 API -referenssi — kaikki POST /api/v2/{toolName}-kutsut
• SMOC:n yhdistäminen REST API:lla
• Public Contacts API
• MCP Claude-, Cursor- ja VS Code -käyttöön