Scoutello API
Scoutello API on palvelinten välinen rajapinta, jolla organisaation yhteystiedot, tehtävät, pöytäkirjat, mahdollisuudet, projektit, virstanpylväät ja tapahtumat synkronoidaan molempiin suuntiin. Se tarjoaa myös vain luku -tilassa lähtevien sähköpostien historian, jäsenhaun määritettäviä jäseniä varten sekä entiteettitietoisen tunnisteiden haun. Tämän version synkronoinnin perusrakenteita ovat asteittaiset GET/list-reitit ja idempotentit eräpäivitykset. Poistotoimintoja tai webhookeja ei ole saatavilla.
Rajapinnan perus-URL-osoite on:
https://admin.scoutello.com/api/v1
Se näkyy myös kohdassa Organisaation asetukset → Kehittäjä/API. OpenAPI-dokumentti on saatavilla osoitteessa:
https://admin.scoutello.com/api/v1/openapi.json
Avaimen luominen ja suojaaminen
Modulaarisissa organisaatioissa CRM-moduulin on oltava aktiivinen avaimelle vaadittujen käyttöoikeuksien lisäksi. Kelvollinen avain ei voi aktivoida puuttuvaa moduulia. Pyynnöt palauttavat HTTP 403 -vastauksen ja virhekoodin module_not_active, jos CRM-käyttöoikeutta ei ole. Organisaation ylläpitäjä voi tarkistaa CRM:n tilan tai aktivoida sen kohdassa Tilaus; yrittää uudelleen, kun käyttöoikeus on aktiivinen.
Organisaation ylläpitäjä voi luoda integraation ja API-avaimen kohdassa Organisaation asetukset → Kehittäjä/API. Koko avain näytetään kerran. Kopioi se salaisuuksien hallintapalveluun ennen valintaikkunan sulkemista; Scoutello ei voi näyttää koko avainta uudelleen.
- Käytä erillistä integraatiota ja avainta jokaiselle ulkoiselle järjestelmälle ja ympäristölle.
- Myönnä vain kyseisen järjestelmän tarvitsemat käyttöoikeudet.
- Älä koskaan lisää avainta selainkoodiin, URL-osoitteeseen, lähdekoodivarastoon, lokeihin, tukiviesteihin tai asiakaspuolen tallennustilaan.
- Kierrätä avaimet säännöllisesti. Kun aktiivisen integraation avain kierrätetään, uusi avain toimii heti ja edellinen avain pysyy voimassa enintään 15 minuuttia, jotta ulkoinen järjestelmä voidaan vaihtaa ilman käyttökatkoa. Aiemmin asetettu vanhenemisaika on edelleen voimassa, joten edellinen avain voi lakata toimimasta aiemmin.
- Jos avain on saattanut paljastua, keskeytä integraatio ennen kierrätystä. Keskeytys hylkää tilapäisesti kaikki integraation avaimet. Jos avain kierrätetään keskeytyksen aikana, päällekkäistä voimassaoloaikaa ei ole: edellinen avain pysyy käytöstä poistettuna ja uusi avain pysyy käytöstä poistettuna, kunnes integraatio jatketaan.
- Peruuta koko integraatio pysyvästi, kun ulkoinen järjestelmä irrotetaan. Peruuttaminen poistaa käytöstä kaikki integraation avaimet, eikä toimintoa voi kumota.
Lähetä avain jokaisessa todennetussa pyynnössä:
Authorization: Bearer YOUR_API_KEY
Bearer-todennus on suositeltava. Asiakkaat, jotka eivät voi määrittää Authorization-otsaketta, voivat käyttää sen sijaan x-api-key-otsaketta. Älä lähetä molempia otsakkeita; pyynnöt, joissa molemmissa otsakkeissa on eri arvot, hylätään.
API on tarkoitettu taustajärjestelmäasiakkaille, eikä se salli selainten välistä alkuperäkäyttöä.
Käytä GET /whoami-toimintoa avaimen määrityksen jälkeen integraation, organisaation, käyttöoikeuksien ja avainrajoitusten tarkistamiseen ilman käyttäjien henkilötietojen hakemista.
Käyttöoikeudet
| Laajuus | Mahdollistaa |
|---|---|
contacts.read | Yhteystietojen luetteloinnin ja noutamisen. Organisaatiotilin yhteystiedot ja käyttöoikeuksia sisältävien jäsenten yhteystiedot jätetään pois. |
contacts.write | Yhteystietojen lisäysten ja päivitysten validoinnin ja käyttöönoton. |
tasks.read | Ei-yksityisten tehtävien luetteloinnin ja noutamisen. |
tasks.write | Tehtävien lisäysten ja päivitysten validoinnin ja käyttöönoton. |
protocols.read | Ei-yksityisten protokollien luetteloinnin ja noutamisen. |
protocols.write | Protokollien lisäysten ja päivitysten validoinnin ja käyttöönoton. |
opportunities.read | Myyntimahdollisuuksien luetteloinnin ja noutamisen. |
opportunities.write | Myyntimahdollisuuksien lisäysten ja päivitysten validoinnin ja käyttöönoton. |
projects.read | Projektien luetteloinnin ja noutamisen. |
projects.write | Projektien ja osallistujien lisäysten ja päivitysten validoinnin ja käyttöönoton. |
milestones.read | Projektin virstanpylväiden luetteloinnin ja noutamisen. |
milestones.write | Virstanpylväiden lisäysten ja päivitysten validoinnin ja käyttöönoton. |
members.read | Hyväksyttyjen jäsenten luetteloinnin siten, että mukana ovat vain jäsenen Customer ID, User ID ja näyttönimi. |
events.read | Tapahtumien ja keskeisten aikataulujen luetteloinnin ja noutamisen. |
events.write | Tapahtumien lisäysten ja päivitysten validoinnin ja käyttöönoton. |
mails.read | Organisaation omistaman lähetettyjen ja epäonnistuneiden lähtevien sähköpostien historian lukemisen. |
mail-drafts.read | Tämän integraation erillisten sähköpostien hyväksyntäluonnosten ja toimitustilan lukemisen. |
mail-drafts.write | Sähköpostiluonnosten laatimisen tai muokkaamisen ihmisen hyväksyntää varten; ei koskaan hyväksymistä tai lähettämistä. |
tags.read | Tuettujen entiteettityyppien valittavissa olevien tunnisteiden etsimisen. |
Yksityisiä tehtäviä ja protokollia ei koskaan palauteta tämän API:n kautta. Puuttuva laajuus palauttaa valtuutusvirheen; sitä ei käsitellä tyhjänä tuloksena.
Muuhun kuin jäseneen kuuluva CRM-yhteystieto voidaan lukea ja siihen voidaan viitata, vaikka se olisi yhdistetty Scoutello-kirjautumiseen. Vastaus sisältää vain organisaation CRM-kentät, ei koskaan User-identiteetti- tai käyttöoikeuskenttiä. Yhteystiedot, joilla on rooli, käyttöoikeuksia, kutsu, hyväksyntä tai organisaatiotilin tila, pysyvät piilotettuina. Kirjautumiseen yhdistetyn yhteystiedon muokkaaminen on edelleen kiellettyä (protected_contact), myös silloin, kun CRM-kentät muutoin säilyisivät ennallaan. Olemassa olevaan luettavaan yhteystietoon viittaaminen tehtävästä tai protokollasta voidaan määrittää käyttämällä contacts.write-arvoa, jolloin ulkoinen linkki voidaan muodostaa vain arvoilla externalId, scoutelloId ja valinnaisella arvolla externalUpdatedAt. Myöhemmissä vain linkin metatietoja koskevissa päivityksissä käytetään externalId-arvoa ja valinnaista externalUpdatedAt-arvoa; jätä käynnistysarvo scoutelloId pois, kun linkitys on tehty. Tämä ei koskaan muuta yhteystietoa tai sen User-käyttäjää. Hyväksytyn jäsenen määrittämiseen käytetään erillistä members.read-projektiota.
Uudet avaimet käyttävät etuliitettä sctl_api_ ja alkavat vain contacts.write-käyttöoikeudella. Kaikki muut käyttöoikeudet on otettava erikseen käyttöön, ja organisaation ylläpitäjän on myönnettävä ne avainta luotaessa tai kierrätettäessä. Olemassa olevat tunnistetiedot säilyttävät nykyiset käyttöoikeutensa ja pysyvät voimassa.
Projektiin yhdistetyt kontaktit ja sähköpostiluonnokset
Kontaktien upsert-toiminnot hyväksyvät valinnaiset projectScoutelloId- / projectExternalId- ja companyScoutelloId- / companyExternalId-parit (valitse yksi kummastakin parista). Kontakti, yrityssuhde ja projektijäsenyys tallennetaan kunkin kohteen osalta atomisesti. Projektijäsenyyden lisääminen edellyttää projects.write-käyttöoikeutta; puuttuvat viittaukset säilyttävät muut suhteet ja jäsenyydet. Kontaktin tietojen luvuissa projectParticipations sisältyy tieto, kun projects.read on myönnetty. Myyntiprojektien agenttien on lisättävä projektiviittaus erikseen myös silloin, kun olemassa olevaa kontaktia käytetään uudelleen.
Erilliset luonnokset käyttävät olemassa olevaa ihmisen tekemää hyväksyntäjärjestelmää ilman työnkulun suoritusta:
| Menetelmä | Polku | Tarkoitus |
|---|---|---|
| GET | /mail-drafts | Sivutettujen, integraation omistamien luonnosten haku; valinnaiset projectScoutelloId- ja status-suodattimet. |
| GET | /mail-drafts/{scoutelloId} | Nykyinen versio, tarkistuslinkki, sisältötiiviste, hyväksyntä-/lähetysstatus ja lopullinen sähköpostin tunnus. |
| GET | /mail-drafts/external/{externalId} | Pysyvän integraation ulkoisen tunnuksen haku. |
| POST | /mail-drafts/batch-upsert | Luonnoksen valmistelun vahvistaminen tai soveltaminen. |
Luonnoksen valmistelu edellyttää käyttöoikeuksia mail-drafts.write, contacts.read ja projects.write. Viitatusta kontaktista tulee projektin osallistuja. Hyväksyjän on oltava organisaation hyväksytty jäsen, jolla on oikeus muokata sähköposteja. Lähettäjän valinnassa käytetään kyseisen jäsenen organisaatio- tai henkilökohtaisia lähettäjäasetuksia, joihin jäsenellä on jo oikeus; mielivaltaisia From-osoitteita ei hyväksytä.
{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}
Tarkista kaikki vahvistustulokset ennen uutta yritystä mode: "apply"-toiminnolla. Lue palautettu tunnus saadaksesi reviewUrl-, draftVersion-, contentHash-, status-, dispatchStatus- ja mailScoutelloId-tiedot. Käytä expectedVersion: 0-tunnusta vain luomiseen ja versioiden päivityksissä viimeksi palautettua versiota. Konteksti ja hyväksyjä ovat muuttumattomia; tarkistetut tai lähetetyt luonnokset hylkäävät muuttuneen sisällön. Identtiset uudelleenyritykset palauttavat alkuperäisen luonnoksen.
Luonnokset näkyvät projektin/yhteyshenkilön sähköpostivälilehdillä ja hallintapaneelin hyväksymisilmoituksissa. API-valmistelu ei lähetä sähköpostia, ilmoitussähköpostit mukaan lukien; olemassa oleva työnkulun ilmoitussähköpostien toiminta säilyy ennallaan. Määritetty henkilö voi muokata vastaanottajia, aihetta, viestiä ja tuettuja liitteitä, tallentaa version ja valita sitten Hyväksy ja lähetä. Integraatiot eivät voi hyväksyä tai lähettää viestejä. Epäonnistunutta tai epäselvää toimitusta ei koskaan yritetä uudelleen automaattisesti. Protokollapohjaisia luonnoksia muunnettaessa protokollat säilytetään ja niiden korvaavat kohteet linkitetään niihin ristiin.
MCP-käyttö
Samaa Scoutello API -avainta ja samoja käyttöoikeusalueita voi käyttää suoratoistettavan HTTP MCP -päätepisteen kanssa:
https://admin.scoutello.com/api/v1/mcp
Määritä MCP-asiakas lähettämään Authorization: Bearer YOUR_API_KEY. Vanha /api/mcp-URL säilyy polun yhteensopivuusaliaksena, mutta uusien asiakkaiden tulee käyttää versioitua päätepistettä. Aiemmat sctl_mcp_-tunnistetiedot eivät kelpaa; korvaa ne Scoutello-integraation API-avaimella.
MCP-työkalut vastaavat suoraan REST-sopimusta ja käyttävät samoja ajonaikaisia skeemoja, vuokraajatarkistuksia, integraation elinkaarta, nopeusrajoitusta ja palvelumenetelmiä. Esimerkiksi contacts_list, contacts_get, contacts_get_by_external_id ja contacts_batch_upsert vastaavat neljää yhteyshenkilöreittiä. Sama toimintamalli koskee tehtäviä, protokollia, mahdollisuuksia, projekteja, virstanpylväitä ja tapahtumia; sähköpostin työkaluihin kuuluvat mails_list ja mails_get, jäsenille members_list ja tunnisteille tags_list.
Palvelin ilmoittaa vain työkalut, jotka nykyisen avaimen käyttöoikeusalueet sallivat. Avain, jolla on contacts.read, voi löytää yhteyshenkilöiden lukutyökalut mutta ei työkalua contacts_batch_upsert; avain, jolla on contacts.write, saa eräpäivitystyökalun mutta ei lukutyökaluja. whoami on aina käytettävissä. Kirjoitustyökaluilla on samat välittömät vaikutukset kuin vastaavilla REST-toiminnoilla, joten käytä mode: "validate"-toimintoa, kun kutsujan tulee tarkastaa erä soveltamatta sitä.
MCP toimii myös palvelinten välisesti eikä mahdollista selainten välistä käyttöä eri alkuperistä. Sen JSON-RPC-siirto edellyttää erillistä URL-osoitetta, joten se ei voi jakaa yksittäisen REST-resurssin URL-osoitetta, vaikka todennus ja tietojen käsittely ovat yhteisiä.
Katso täydelliset asiakkaan määrityksiä, vahvistusta, työkalujen vastaavuuksia ja vianmääritystä koskevat ohjeet MCP-integraatio-oppaasta.
Tietueiden lukeminen
Yhteyshenkilöt, tehtävät, protokollat, mahdollisuudet, projektit, virstanpylväät ja tapahtumat käyttävät samoja lukureittejä:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
Korvaa contacts arvolla tasks, protocols, opportunities, projects, milestones tai events muiden synkronointiresurssien osalta. externalId näkyy lukudatasiirto-objektissa, kun tämä integraatio on linkittänyt tietueen.
Listavastauksen rakenne on seuraava:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit-arvon on oltava välillä 1–100. Tulokset järjestetään sen tosiasiallisen ajankohdan mukaan, jolloin niiden julkinen API-esitys muuttui, ja sen jälkeen Scoutello-tunnuksen mukaan. Tämä tosiasiallinen ajankohta voi olla palautettua entiteettiä updatedAt myöhempi, jos integraatiolinkin metatiedot muuttuivat. Kohdistimet ovat läpinäkymättömiä: tallenna ja lähetä ne muuttamattomina äläkä päättele niiden sisällöstä mitään.
Ensimmäinen vastaus määrittää snapshotAt-arvon kyseistä läpikäyntiä varten. Seuraa nextCursor-arvoa, kunnes hasMore on false, ennen uuden inkrementaalisen luvun aloittamista. Näin sivutuksen aikana muuttuvat tietueet eivät tee nykyisestä läpikäynnistä epävakaata.
Inkrementaalista synkronointia varten käsittele kaikki kohdistinsivut ja tallenna sitten kyseisen läpikäynnin snapshotAt ylärajana käytettäväksi aikaleimaksi. Välitä se seuraavan läpikäynnin ISO 8601 -muotoisena updatedSince-arvona. Alaraja sisältyy hakuun, joten valmistuneen tilannekuvan uudelleenyritys voi palauttaa rajalla olevia tietueita, mutta ei voi ohittaa niitä.
Yksittäisen tietueen vastauksen rakenne on seuraava:
{
"data": {},
"requestId": "request-id"
}
Yksittäisen kontaktin vastaukset sisältävät myös relations-taulukon. Jokainen suhde säilyttää Scoutello-suhdetunnuksensa, luontiaikansa, tyyppinsä, muistiinpanonsa sekä connectedFrom- ja connectedTo-kontaktiviittaukset. Kontaktiviittaukset sisältävät Scoutello-tunnuksen ja tämän integraation ulkoisen tunnuksen, jos sellainen on olemassa. Kontakteja, jotka jäävät API:n organisaatiotason käyttöoikeuksien yksityisyysrajoituksen ulkopuolelle, ei tuoda esiin suhteiden kautta.
Kontaktien luettelovastaus pysyy suppeana eikä sisällä suhteita. Kun suhteiden tiedot ovat tarpeen, käytä jompaakumpaa yksittäisen kontaktin reittiä.
Työsuodattimet ja kohdistimen laajuus
Kontaktien luettelot hyväksyvät search-, type-arvot (person, company, supplier, other), status- ja tagIds-arvot. Haku poistetaan alusta ja lopusta, kirjainkoko ohitetaan, ja se rajoittuu 200 merkkiin / 10 välilyönnein eroteltuun tunnukseen. Jokaisen tunnuksen on esiinnyttävä vähintään yhdessä seuraavista: firstName, lastName tai companyName, mukaan lukien lastName-tunnukseen tallennetut vanhat yritysnimet. Merkit, kuten % ja _, täsmäytetään kirjaimellisesti. Tunnisteissa käytetään any-of-täsmäytystä 1–50 tunnuksella. Kaikki annetut suodattimet yhdistetään AND-operaatiolla. REST koodaa tunnisteiden tunnukset toistuvina parametreina; MCP toimittaa taulukon:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
Kontaktikohdistimet sidotaan organisaatioon, integraatioon ja kaikkiin suodattimiin. Säilytä suodattimet jokaisella sivulla; suodattimen muuttaminen hylkää kohdistimen. Tunnisteiden järjestys tai kaksoiskappaleet sekä haun tunnusten järjestys, kirjainkoko tai välilyönnit eivät muuta suodattimen tosiasiallista sisältöä.
Work-loendite marsruudid aktsepteerivad järgmisi täiendavaid filtreid; muud ressursi- ja väljapaarid lükatakse tagasi:
| Ressurss | Filtrid |
|---|---|
| Ülesanded | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Protokollid | projectScoutelloId, milestoneScoutelloId, status (draft või final) |
| Võimalused | projectScoutelloId, stage, ownerScoutelloUserId |
| Projektid | status, assignedContactScoutelloId |
| Verstapostid | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
dueBefore on välistav; dueAfter on kaasav. Neid võrreldakse ülesande tähtaja või verstaposti lõppkuupäevaga; ilma selle kuupäevata kirjed ei vasta tingimusele. Esitage ajavöönditeavet sisaldavad ISO-kuupäevaajad. Kõiki filtreid rakendatakse enne lehekülgede kaupa laadimist. Jätkake kursorit täpselt samade filtritega, sealhulgas updatedSince, ning sama organisatsiooni ja integratsiooniga. Lehekülje suurust võib muuta. Pärast seda väljalaset tuleb vanad ulatuseta kursorid taaskäivitada salvestatud kõrgeima ajatempli juurest.
Projektid, verstapostid, määrangud ja märkmed
GET /members (MCP members_list) kasutab standardset lehekülgede kaupa laadimist ja nõuab members.read. See tagastab scoutelloId (liikme Customer ID), scoutelloUserId (User ID) ja displayName. Kuvatakse ainult aktsepteeritud rolliga organisatsiooniliikmed; otsing ei avalda e-posti aadresse ega õigusi.
Ülesanded aktsepteerivad assignedScoutelloUserIds; võimalused kasutavad ownerScoutelloUserId. Projektid ja verstapostid kasutavad assignedContacts: [{"scoutelloId":"member-customer-id"}]. Määrangute tegemiseks on vaja mandaadi organisatsiooni aktsepteeritud liikmeid. Määrangute puudumine jätab need muutmata; [] eemaldab need. Projektide, verstapostide, ülesannete ja protokollide import toimub vaikselt: määrangute teavitusi ega muid teateid ei saadeta.
Sündmus assignedContacts toetab loetavaid CRM-kontakte ja liikme Customer ID alusel lisatud aktsepteeritud liikmeid. Aktsepteeritud liikmed ei ole tavaliste CRM-kontaktiviite ega välislinkide sihtmärkidena saadaval; meeskonnavastutuse määramiseks kasutage liikme määrangu välja.
Luo virstanpylväitä käyttämällä name-arvoa sekä joko projectScoutelloId- tai projectExternalId-arvoa. Ne tukevat description-arvoa (Markdown), status-arvoa (open, in_progress, completed, closed), nullable-arvoja startDate/endDate, order-arvoa (oletusarvo on 0) sekä assignedContacts-arvoa. Päivämäärä ei voi päättyä ennen alkamispäivämäärää. Jokaisella virstanpylväällä on integraatioon rajattu pysyvä ulkoinen linkki. Projektia ei voi vaihtaa API:n kautta. Luonti- ja päivitystoiminnot lokalisoivat nimen ja kuvauksen organisaation kielelle.
Tehtävissä ja protokollissa voi käyttää projekti-, virstanpylväs- ja mahdollisuusviittauksia joko <entity>ScoutelloId- tai <entity>ExternalId-muodossa, esimerkiksi milestoneExternalId. Käytä kussakin suhteessa vain yhtä kirjoitusasua, myös tyhjennettäessä arvollla null. Kaikkien suhteiden on kuuluttava tunnistetiedon organisaatioon. Pelkkä virstanpylväsviittaus päättelee projektin. Ristiriitainen projekti tai projektin nimenomainen tyhjentäminen samalla, kun sen virstanpylväs säilytetään, hylätään. Projektiin liitetyn mahdollisuuden projektin on vastattava työn projektia. Puuttuvat suhteet säilyttävät nykyiset arvot; nimenomainen null tyhjentää suhteen, jos jäljelle jäävä asiayhteys on kelvollinen. Lukutuloksissa näytetään molemmat tunnistekirjoitusasut ja tehtävämääritykset.
Tehtävien suunnittelu ja työnkulut
Tehtävän status on tehtävän tehokkaassa työnkulussa olevan tilan muuttumaton avain, ei kiinteä enumeraatio. Lue organisaation ja projektin käytettävissä olevat työnkulut käyttämällä GET /task-workflows-arvoa ja tasks.read-laajuutta. Jokainen tila sisältää avaimen, selitteen, elinkaaren type (backlog, unstarted, started, completed tai cancelled), värin, järjestyksen, oletusilmaisimen ja arkistointitilan. Projektimerkinnät ilmaisevat, periytyykö organisaation työnkulku. Työnkulun määrityksiä hallitaan edelleen hallintapaneelissa.
Tehtävät hyväksyvät nullable-arvon priority (low, medium, high tai urgent) ja estimatedEffortMinutes-arvon sekä nullable-arvot startDate ja dueDate. Tehtävien lukutuloksiin sisältyvät denormalisoitu statusType, ylätason viite, tiiviit alitehtäväviitteet sekä blockedBy- ja blocks-viitteet.
Luo tai päivitä yksitasoinen alitehtävä käyttäen arvoa parentTaskScoutelloId tai parentTaskExternalId; null nostaa sen päätason tehtäväksi. Riippuvuudet ilmoitetaan blockedBy- ja blocks-kentissä { "scoutelloId": "..." }- tai { "externalId": "..." }-viitteiden taulukkoina. Puuttuvien suhdekenttien nykyiset arvot säilytetään, kun taas tyhjä riippuvuustaulukko poistaa kyseisen suunnan riippuvuudet. API hylkää sisäkkäiset alitehtävät, emo–lapsi-riippuvuudet, organisaatioiden väliset riippuvuudet, kaksoiskappaleet, viittaukset itseensä sekä suorat ja välilliset syklit.
Tehtäväluettelon suodattimet hyväksyvät täsmällisen työnkulun status, elinkaaren statusType, priority-arvon, parentState-arvon (top_level, subtask tai parent) sekä blockedState-arvon (blocked, blocking tai unblocked).
Protokollat hyväksyvät lisäksi status: "draft" | "final"-arvon (uusien tietueiden oletusarvo on final). Uusi protokolla edellyttää arvoja type ja date sekä joko yhteyshenkilöä tai kelvollista projekti-/välitavoitekontekstia. contactExternalId: null poistaa yhteyshenkilön vain, jos projekti-/välitavoitekonteksti säilyy. Sisäisiä projektimuistiinpanoja voidaan siten luoda ja lukea ilman asiakkaan keksimistä. Luonnos/valmis kuvaa muistiinpanon tilaa eikä koskaan lähetä viestintää. Yksityiset tehtävät ja protokollat eivät edelleenkään ole käytettävissä.
Projektin osallistujat
Projektin participants sisältää lisäyksiä ja päivityksiä, joiden avaimena on contact-viite, esimerkiksi:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
Osallistujat kuvaavat projektiin liittyviä prospekteja ja asiakkaita; vastuulliset jäsenet määritetään tehtävien kautta. Puuttuvat osallistujat, tyhjä taulukko ja puuttuvat osallistujakentät säilyttävät nykyiset tiedot. null tyhjentää role-, notes- tai groupScoutelloId-arvon. Samassa hyötykuormassa olevat päällekkäiset ratkaistut yhteyshenkilöt hylätään. Ryhmien on kuuluttava jo valittuun projektiin; lukutulokset sisältävät participantGroups-arvon (tunnus/nimi) sekä osallistujien tunnukset, yhteyshenkilöt, roolin, muistiinpanot ja ryhmätunnuksen. Osallistujien poistaminen tai ryhmien luominen on tällä hetkellä mahdollista hallintapaneelissa.
Tietueiden eräpäivitys
Kirjoita enintään 100 tietuetta resurssin eräreitillä:
POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}
Tehtäväerät ratkaisevat tehtävätietueet ennen emo- ja riippuvuussuhteiden käyttöönottoa. Tämä kaksivaiheinen käsittely mahdollistaa sen, että emo-, estäjä- tai estetty tehtävä voi viitata samassa erässä luotuun toiseen tehtävään tämän ulkoisella tunnuksella tietueiden järjestyksestä riippumatta.
Käytä kunkin resurssin kenttien ja validointirajoitteiden määrittämiseen OpenAPI-dokumenttia. Jokaisella tietueella on oltava vakaa externalId, jonka pituus on 1–200 merkkiä. Käsittele sitä läpinäkymättömänä teknisenä tunnisteena: älä käytä sähköpostiosoitetta, nimeä, API-salaisuutta tai muita henkilötietoja. externalUpdatedAt on valinnainen, mutta erittäin suositeltava, jos lähdejärjestelmä tarjoaa luotettavan muokkausajankohdan.
Pyynnön rungon enimmäiskoko on 1 MiB. mode käyttää oletusarvona arvoa apply:
applyvalidoi hyväksytyt tietueet ja kirjoittaa ne.validatesuorittaa saman validoinnin ja täsmäytyksen ilman kirjoittamista ja palauttaawould_*-tulokset.
Kontaktien tuonnissa matchByEmail voidaan asettaa pyynnössä arvoon true. Oletusarvo on false; ulkoinen tunniste on turvallisempi oletusarvoinen identiteettiraja.
Puuttuvat kentät säilyttävät nykyisen arvon. Nimenomainen null tyhjentää nullable-kentän, ja annettu tyhjä määritys- tai tunnistejoukko tyhjentää kyseisen yhteyden. Projektin participants ovat lisääviä upsert-toimintoja: tyhjä taulukko jättää osallistujaluettelon ennalleen. Kontaktien, tehtävien, mahdollisuuksien ja tapahtumien tunnistekirjoituksissa käytetään Scoutello-tunnisteiden tunnuksia. Suhteiden ulkoiset tunnisteet ratkaistaan vain nykyiseen integraatioon kuuluvien linkkien kautta, kun taas omistajuuteen tai vastuuhenkilöön käytettävien Scoutello-käyttäjätunnusten on viitattava nykyisen organisaation hyväksyttyihin jäseniin.
Mahdollisuuden luominen edellyttää tiliä tai kontaktia, ja hävitetyille mahdollisuuksille on annettava häviämisen syy. Rahamäärät ilmoitetaan kokonaisina sentteinä. Projektien ja tapahtumien nimet ja kuvaukset luetaan ja kirjoitetaan organisaation määritetyllä kielellä. Tapahtumien kirjoituksissa tuetaan nimenomaisia päivämääriä sekä päivittäistä, viikoittaista tai kuukausittaista toistuvuutta poikkeuksineen; julkaistut näkyvyystasot ovat edelleen Scoutellon oikeudellisen valmiuden ehtojen alaisia. API ei tarjoa tapahtumien lipunmyyntiä, osallistujia, mediaa, malleja, uutiskirjeitä, yhteistöitä tai muita tapahtumahallinnan edistyneitä toimintoja.
Tunnisteiden etsiminen
Käytä tunnisteiden päätepistettä ennen tagIds-arvon toimittamista:
GET /tags?entity=events&type=category
entity on pakollinen, ja se hyväksyy arvon contacts, tasks, opportunities tai events. Se yhdistetään vastaavaan tallennettuun tunnisteen relevanssiin. type on valinnainen, ja se hyväksyy arvon category tai attribute. Valittavat luokat voivat olla organisaation omia tai yleisiä; valittavat attribuutit ovat peräisin Scoutellon kuratoidusta yleisestä attribuuttijoukosta. Tulokset sisältävät scoutelloId-arvon, organisaation kielelle lokalisoidun nimen, type-arvon ja relevancy-arvon. Organisaatioiden väliset, väärän relevanssin tunnisteet ja valitsemattomat tunnistetunnukset hylkäävät kyseisen eräalkion.
Lähtevän sähköpostin historian lukeminen
Sähköpostihistoria on vain luku -tilassa:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Vain organisaation omistamat sähköpostit, joiden tila on sent tai failed, palautetaan. Vastaukset sisältävät yleiset tallennetut otsakkeet ja rungon, piilokopiot, tilan ja aikaleimat, projekti-, tapahtuma- ja uutiskirjeviittaukset, liitteiden tunnisteet ja tyypit sekä yhteenvedon vastaanottajien toimitus-, avaus-, klikkaus-, palautus-, valitus- ja hylkäystilastoista. Luonnoksia, jonossa olevia tai ajoitettuja sähköposteja, vastaanottajakohtaisia rivejä, renderöityjä tilannevedoksia, palveluntarjoajan raakoja virheitä tai liitteiden lataus-URL-osoitteita ei koskaan paljasteta. Myöhempi vastaanottajan toimitustilan päivitys siirtää sähköpostin tosiasiallista synkronoinnin aikaleimaa eteenpäin, jolloin sähköposti näkyy jälleen inkrementaalisissa luvuissa. Sähköpostien kirjoittamiseen ei ole reittejä.
Käytön tulos voi olla created, updated, linked, unchanged, stale_ignored tai rejected. Validoinnissa käytetään arvoja would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale tai rejected. Kelvollinen eräpyyntö palauttaa HTTP 200 -vastauksen, vaikka yksittäisiä tietueita hylättäisiin, joten jokainen kohde ja vastauksen yhteenveto on aina tarkistettava. Säilytä vastaus requestId, kun pyydät Scoutello-tukea tutkimaan virhettä.
Aikaleimat ja ristiriidat
Kun externalUpdatedAt on mukana, Scoutello käyttää sitä vanhentuneiden muutosten hylkäämiseen ilman, että muu erä epäonnistuu. stale_ignored-tulos on lopullinen kyseisen vanhemman hyötykuorman osalta; hae nykyinen tietue ennen kuin päätät uuden version lähettämisestä.
Käsittele aikaleimoja UTC-aikavyöhykkeen ISO 8601 -arvoina. Säilytä niiden alkuperäinen tarkkuus äläkä korvaa lähdetietueen muokkausaikaa synkronointityön suoritusajalla.
Idempotenssi
Idempotenssiraja on integraatio ja externalId. Scoutello vertaa kanonisen hyötykuorman tiivistettä ja valinnaista externalUpdatedAt-arvoa, joten saman tietueen uudelleenyritys ei luo kaksoiskappaleita ja voi palauttaa arvon unchanged.
Kun käytössä on externalUpdatedAt, sama aikaleima ja hyötykuorma on unchanged, vanhempi aikaleima on stale_ignored, ja sama aikaleima eri hyötykuormalla on versiokonflikti. Jos linkki ei ole koskaan hyväksynyt aikaleimaa, sama aikaleimaton hyötykuorma säilyy tilassa unchanged, kun taas muuttunut hyötykuorma käsitellään saapumisjärjestyksessä. Kun linkki on hyväksynyt aikaleiman, muuttunut hyötykuorma, josta externalUpdatedAt puuttuu, hylätään versiokonfliktina, jotta versioimaton data ei voi korvata versioitua tilaa. Siksi lähteen muokkausaikaleimojen käyttöä suositellaan vahvasti.
Tarkastusloki
Hyväksytyt API:n luonti-, päivitys- ja vain linkitystä koskevat synkronointitoiminnot näkyvät Scoutellon muutoslokeissa lähteenä Public API, ja ne yhdistetään vastuussa olevaan integraatioon. Toimintojen yhteenvedot säilyttävät pyyntöjen tunnisteet ja tulosten kokonaismäärät vianmääritystä varten; tietueiden sisältöjä tai API-salaisuuksia ei säilytetä.
Virheet ja uudelleenyritykset
Pyyntötason virheet käyttävät tätä envelope-rakennetta:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
Yritä HTTP 429- ja tilapäiset 5xx-vastaukset uudelleen eksponentiaalisella viiveellä ja jitterillä. Noudata arvoa Retry-After, jos se on mukana. Verkkovirhe on voinut ilmetä sen jälkeen, kun Scoutello hyväksyi pyynnön; saman erän lähettäminen uudelleen on turvallista, koska jokainen tietue on idempotentti ulkoisen tunnisteen ja kanonisen sisällön perusteella. Älä yritä automaattisesti uudelleen todennus-, käyttöoikeus-, validointi- tai versioristiriitoihin liittyviä virheitä tai yksittäisiä rejected-tuloksia muuttamatta pyyntöä.
Suositeltu kaksisuuntaisen synkronoinnin silmukka
- Kutsu asennuksen aikana
/whoamija varmista odotettu organisaatio sekä käyttöoikeusalueet. - Lue kaikki viimeksi suoritetun ylävesimerkin jälkeen muuttuneet sivut ja toteuta muutokset ulkoiseen järjestelmään idempotentisti.
- Lähetä ulkoiset muutokset osoitteeseen
/batch-upsertkäyttämällä pysyviä ulkoisia tunnisteita ja lähdejärjestelmän muokkausaikaleimoja. - Tallenna tarkistuspisteet vasta, kun kaikki sivut ja kohteiden tulokset on käsitelty.
- Ratkaise ristiriidat lähdejärjestelmän omistajuussääntöjen mukaisesti; älä jäljittele poistoja lähettämällä tyhjiä tietueita.
Scoutello ei tarkoituksella tarjoa tässä ensimmäisessä versiossa julkista poistoreittiä. Käsittele poistamis- tai arkistointikäytännöt API:n ulkopuolella, kunnes dokumentoitu elinkaaritoiminto otetaan käyttöön.
Ihmisen tarkistettaviksi tarkoitetut sosiaalisen median julkaisut
Sosiaalisen median API valmistelee julkaisut nimetylle ihmistarkistajalle. Se ei voi hyväksyä tai julkaista niitä. REST ja MCP käyttävät samoja käyttöoikeusalueita ja palvelua.
| Käyttöoikeusalue | /api/v1:n alaiset päätepisteet |
|---|---|
social-channels.read | GET /social-channels |
social-posts.read | GET /social-posts, GET /social-posts/{scoutelloId} |
social-post-drafts.read | GET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId} |
social-post-drafts.write | POST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize |
Uudet käyttöoikeusalueet on myönnettävä erikseen. Olemassa olevat tunnistetiedot eivät saa lisäkäyttöoikeuksia. Käytä kohdetta members.read jäsentunnisteiden selvittämiseen ja valitse julkaisuoikeudet omaava tarkistaja (newsletter.edit). Luonnokset eivät edellytä CRM-yhteyshenkilöä tai projektia.
{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}
Käytä publishMode: "now"- ja scheduledAt: null-tunnisteita julkaisun tekemiseen hyväksynnän jälkeen. Jokainen
kanavaversio sisältää koko tekstin, asetukset ja median tunnisteet järjestyksessä.
Kanavien haku palauttaa tuetut muodot, rajoitukset ja asetukset. Tällä hetkellä
tuettuja kanavia ovat LinkedIn-profiilit ja -sivut, Facebook, Instagram ja Threads.
Instagram vaatii mediaa. Versio voi sisältää enintään kymmenen kuvaa tai videota.
Erät voivat sisältää enintään 100 yksilöllistä ulkoista tunnistetta nykyisen 1 MiB:n
pyyntörajoituksen puitteissa. mode: "validate" tarkistaa viittaukset ja versiot tallentamatta luonnoksia,
lataamatta resursseja, luomatta ilmoituksia tai lisäämättä töitä jonoon. Soveltamisen tulokset sisältävät
tunnisteet, tarkistuslinkit, versiot ja tietuekohtaiset tulokset. Osittaiset virheet eivät
peru onnistuneiden sisartietueiden muutoksia. Ilmoitusvirhe palauttaa varoituksen sekä tallennetun
tarkistus-URL-osoitteen.
Hae nykyinen draftVersion ennen odottavan luonnoksen muokkaamista. Identtiset
uudelleenyritykset ovat idempotentteja ja säilyttävät myöhemmin tehdyt ihmisten muutokset. Tarkistajia ei voi vaihtaa
suoraan. Hyväksynnän tai hylkäyksen jälkeen käytä uutta ulkoista tunnistetta uuden ehdotuksen tekemiseen.
Luonnosten lukeminen on rajattu kutsuvaan integraatioon. Julkaisuhistoria kattaa kaikki
organisaatiossa pysyvästi säilytetyt Scoutello-kampanjat, jotka on luotu Scoutellolla, mukaan lukien hallintapaneelin,
komentosarjan ja vanhat Scoutello-julkaisut. Ulkoisten kanavien historiaa ei tuoda.
Luetteloissa käytetään vakioparametreja limit, cursor ja updatedSince. Julkaisut ja
luonnokset hyväksyvät lisäksi parametrit channelId, status, after, before ja search; säilytä
kaikki suodattimet myöhempien kohdistinsivujen pyynnöissä. Päivämääräsuodattimet koskevat julkaisuaikaa
(välittömästi käsiteltävien luonnosten kohdalla luontiaikaa). Luonnoksen status suodattaa hyväksynnän
tilan perusteella; julkaisun status vastaa kampanjan tai kanavakohtaisen toimituksen tilaa. Lukeminen näyttää
viimeksi tunnetun toimitustilan, kanavakohtaiset virheet, julkiset linkit ja täsmäytysten
aikaleimat. Luonnosten inkrementaaliset haut heijastavat myös kampanjan toimitusten muutoksia.
Median lataaminen
- Kutsu
POST /social-media/uploadskäyttäenclientUploadId-,filename-,contentType- jasize-arvoja tavuina sekä alkuperäisten tavujen pienaakkosin kirjoitettua heksadesimaalistasha256-arvoa. Tuetut tyypit ovat PNG, JPEG, WebP, MP4, WebM, QuickTime ja M4V. Latauksen enimmäiskoko on 500 MiB. - Lähetä alkuperäiset tavut HTTP
PUT-pyynnöllä palautettuunupload.url-osoitteeseen käyttäen sen otsakkeita. Latausosoitteet vanhenevat 15 minuutin kuluttua. Käytä saman tiedoston uudelleenyrityksiinclientUploadId-arvoa; vanhentuneet istunnot tai eri tiedostot edellyttävät uutta tunnistetta. - Kutsu
POST /social-media/uploads/{assetId}/finalizeja lähetä JSON-runkona{}. Viimeistely tarkistaa koon, tyypin, allekirjoituksen ja tarkistussumman, lukitsee yksityisen kopion ja palauttaamediaIds-kohteen tunnisteen. Viimeistelyn toistaminen on turvallista.
Latauksen omistajuus määräytyy organisaation ja integraation perusteella. Luonnokset voivat viitata organisaationsa viimeisteltyihin kohteisiin. Esikatseluosoitteet ovat väliaikaisia; hae luonnos uudelleen niiden päivittämiseksi. Viimeistellyille kohteille ei koskaan myönnetä latausosoitteita.
Ihmistarkistus ja toimitus
Tarkistaja saa koontinäyttöön ilmoituksen ja voi avata julkaisun Postings-näkymästä tai sen tarkistusosoitteesta. Muokkaaminen luo uuden muuttumattoman version. Hyväksynnässä käytetään näytettyä versiota ja sisällön tiivistettä, tarkistetaan jäsenyys, kanavat ja kohteet uudelleen ja luodaan atomisesti yksi pysyvä kampanja. Jos ehdotettu ajankohta on jo mennyt, tarkistajan on tallennettava uusi ajankohta erikseen tai valittava julkaiseminen hyväksynnän yhteydessä.
Jonon uudelleenyritykset käyttävät samaa kampanjaa ja sen alustojen vastaanottotunnisteita. Hyväksyttyjä kampanjoita ei voi muokata suoraan. Koontinäytön kautta peruminen säilyttää hyväksyntähistorian ja mediatiedostot; peruminen ei voi keskeyttää käynnissä olevaa lähetystä. Hae luonnos tai kampanja, jotta voit erottaa hyväksynnän varsinaisesta alustatoimituksesta.