SMOCin yhdistäminen REST API:in

Yksinkertainen opas, jossa näytetään, miten yhdistät SMOC REST API:in omasta koodistasi, synkronointitöistäsi tai CRM-putkistasi. Asiakasavaimet ovat oletuksena yrityskohtaisia ja vain lukuoikeudella. Kirjoitusoikeudelliset avaimet voivat tehdä rajoitettuja kirjoituksia, kuten lähettää viestejä saapuneet-kansioon; niillä ei voi muokata virtojen graafeja, julkaista virtoja tai käynnistää LinkedIn-kontaktointikampanjoita. Superkäyttäjäavaimilla voi tallentaa virta- ja teema-luonnoksia samoilla POST /api/v2/{toolName}-kutsuilla; julkaisu vaatii silti henkilön Studio- tai Console-ympäristössä. Domain-työkalut löytyvät REST v2:sta nimellä POST /api/v2/{toolName} (samat käsittelijät kuin MCP:ssä). Täydellinen kutsulista: REST v2 API -viite. GET /api/company/mongocontact on tarkoitettu Zapierille.

Hanki API-avaimesi

1. Siirry kohtaan Asetukset → Integraatiot → API SMOC Consolessa.
2. Halutessasi anna avaimelle nimi ja voimassaoloaika (7, 30 tai 90 päivää). Jätä voimassaolo Ei vanhene -tilaan, jos et halua sen vanhenevan.
3. Luo avain ja kopioi se heti — se näytetään vain kerran, joten tallenna se turvalliseen paikkaan.

Avaimesi on sidottu yritykseesi. Jokainen sillä tehty pyyntö kohdistuu automaattisesti yrityksesi tietoihin. Uuden avaimen luominen ei poista aiempia avaimia. Myönnetyt avaimet näkyvät samalla sivulla — poista käyttämättömät avaimet sieltä. MCP-sivu käyttää samoja toimintoja — katso kuvakaappaus MCP-oppaasta.

Perus-URL

Perus-URL: https://api.smoc.ai

Täysi kontaktien päätepiste:

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

Autentikointi

Legacy-kontaktit: lähetä avain mukautetussa HTTP-otsikossa nimeltä token. REST v2 hyväksyy Authorization: Bearer tai token.

GET /api/company/mongocontact HTTP/1.1
Host: api.smoc.ai
token: YOUR_SMOC_API_KEY

Älä käytä Clerk-salaisia avaimia (sk_…) tai julkaistavia avaimia (pk_…).

Mitä toimintoja on olemassa

REST v2 — POST /api/v2/{toolName}

Peilaa MCP domain -työkaluja (contacts_search, cpcs_overview, inbox_threads_list ja muut). OpenAPI: GET /api/v2 tai GET /api/v2/openapi.json. Katso REST v2 -viite.

Listaa yrityksen kontaktit — GET /api/company/mongocontact (Zapier / yhteensopivuus)

Palauttaa sivun yrityksen kontakteja avaimen perusteella sekä koontiluvut.

Mitä se palauttaa

• Kontaktitiedot: nimi, sähköposti, puhelin, tila, osoite, viimeisin keskustelupäivä, vierailu-/UTM-historia, kyselyvastaukset, mukautetut tekstikentät, suosittelu- ja kampanjatiedot, jos kerätty. Positiiviset viestivirran älyliidit ovat tavallisia liidejä (status: "1") ja sisältävät myös leadSentiment, leadCapturedAt ja tags, jos saatavilla.
• leadsCount — kontaktit, joiden tila on liidi (myös asettamaton)
• customerCount — kontaktit, joiden tila on asiakas

Luvut kattavat kaikki yrityksen kontaktit, eivät vain nykyisen sivun.

Kyselyparametrit

Parametri	Oletus	Kuvaus
limit	100	Palautettavien kontaktien enimmäismäärä (1–500)
sortByField	(ei arvoa)	Järjestä laskevasti createdAt, updatedAt, lastConversationDate tai leadCapturedAt mukaan
status	(ei arvoa)	Suodata kontaktin tilan mukaan. status=1 on vakio liidikysely ja sisältää positiiviset viestivirran älyliidit

Kontaktin tilan arvot: "1" liidi, "2" asiakas, "3" menetetty, "4" konvertoitu.

Asiakasavaimilla ei voi luoda, päivittää tai poistaa kontakteja. Mongocontactissa ei ole kursori-sivutusta — käytä limit ja seuraa nähtyjä ID:itä asiakaspäässä, tai käytä Zapier -pollingia. Monipuolisempi haku on POST /api/v2/contacts_search.

Kenttäkohtaiset vastausrakenteet löytyvät Public Contacts API -viitteestä.

Esimerkkipyyntö

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

Mitä asiakas-API:ssa ei ole

Kirjoitusoikeudellisillakaan avaimilla ei voi julkaista virtaa, vaihtaa live-tilaa (flowcharts_set_active), poistaa tietueita tai käynnistää LinkedIn-kontaktointikampanjaa. Saapuneet-kansion lähetys on valinnainen kirjoitusoikeudellisella avaimella (inbox_threads_send, vain teksti, vaatii idempotencyKey). Käytä SMOC MCP:tä Claudella, Cursorilla tai VS Codessa samoihin työkaluihin MCP:n kautta.

Tietoturvahuomiot

• Avain näytetään vain kerran luotaessa — tallenna se salasananhallintaan tai ympäristömuuttujaan.
• Älä koskaan lisää avainta Git-repositorioon.
• Asiakasavaimet rajoittuvat yrityksesi tietoihin. Oletusavaimet ovat vain lukuoikeudella; kirjoitukset, kuten saapuneet-lähetys, ovat valinnaisia.
• Poista käyttämättömät avaimet myönnettyjen avainten listalta kohdasta Asetukset → Integraatiot → API.

Vianmääritys

• 401 Puuttuva tunnisteotsikko: lähetä token: <key>, älä Authorization: Bearer.
• 401 Virheellinen tai peruttu tunniste: varmista, että avain on oikea eikä sitä ole peruttu.
• 422 limit ei saa ylittää 500: laske limit-kyselyparametria.
• 422 Virheellinen tila-arvo: käytä 1, 2, 3 tai 4.

Katso myös

• REST v2 API -viite — kaikki POST /api/v2/{toolName}-kutsut
• SMOCin yhdistäminen REST API:in
• Public Contacts API
• MCP Claudelle, Cursorille ja VS Codelle