Scoutello API
Scoutello API-et er et server-til-server-API for toveis synkronisering av en organisasjons kontakter, oppgaver, protokoller, muligheter, prosjekter, milepæler og hendelser. Det tilbyr også skrivebeskyttet historikk over utgående e-post, oppslag av medlemmer som kan tildeles, og utforsking av enhetsbevisste tagger. Inkrementelle GET/list-ruter og idempotente batch-opprettinger eller -oppdateringer er synkroniseringsprimitivene i denne versjonen. API-et tilbyr ikke sletteoperasjoner eller webhooks.
API-bas URL er:
https://admin.scoutello.com/api/v1
Den vises også under Organisasjonsinnstillinger → Utvikler/API. OpenAPI-dokumentet er tilgjengelig på:
https://admin.scoutello.com/api/v1/openapi.json
Opprette og beskytte en nøkkel
For modulære organisasjoner må CRM-modulen være aktiv i tillegg til de nødvendige omfangene for nøkkelen. En gyldig nøkkel kan ikke aktivere en manglende modul. Forespørsler returnerer HTTP 403 med feilkoden module_not_active når CRM-tilgang ikke er tilgjengelig. En organisasjonsadministrator kan se gjennom eller aktivere CRM under Abonnement; prøv på nytt etter at tilgangen er aktiv.
En organisasjonsadministrator kan opprette en integrasjon og API-nøkkel under Organisasjonsinnstillinger → Utvikler/API. Hele nøkkelen vises én gang. Kopier den til en hemmelighetsbehandler før dialogboksen lukkes; Scoutello kan ikke vise hele nøkkelen på nytt.
- Bruk en separat integrasjon og nøkkel for hvert eksternt system og miljø.
- Gi bare de omfangene systemet trenger.
- Legg aldri en nøkkel i nettleserkode, en URL, kildekontroll, logger, støttemeldinger eller klientlagring.
- Roter nøkler etter en fast plan. Når en aktiv integrasjon roteres, fungerer erstatningsnøkkelen umiddelbart, mens den forrige nøkkelen forblir gyldig i maksimalt 15 minutter slik at det eksterne systemet kan bytte uten nedetid. En tidligere angitt utløpstid gjelder fortsatt, så den forrige nøkkelen kan slutte å fungere tidligere.
- Hvis en nøkkel kan ha blitt eksponert, sett integrasjonen på pause før den roteres. En pause avviser midlertidig alle nøklene til integrasjonen. En rotering mens integrasjonen er satt på pause gir ingen overlapp: Den forrige nøkkelen forblir deaktivert, og erstatningsnøkkelen forblir deaktivert til integrasjonen gjenopptas.
- Tilbakekall hele integrasjonen permanent når et eksternt system kobles fra. Tilbakekalling deaktiverer alle nøklene og kan ikke angres.
Send nøkkelen med hver autentiserte forespørsel:
Authorization: Bearer YOUR_API_KEY
Bearer-autentisering anbefales. Klienter som ikke kan angi Authorization, kan bruke x-api-key i stedet. Ikke send begge overskriftene; forespørsler med ulike verdier i begge overskriftene avvises.
API-et er beregnet for backend-klienter og tillater ikke tilgang fra nettlesere på tvers av opphav.
Bruk GET /whoami etter at en nøkkel er konfigurert, for å bekrefte integrasjonen, organisasjonen, omfangene og nøkkelgrensene uten å hente personopplysninger om brukere.
Omfang
| Omfang | Gir tilgang til |
|---|---|
contacts.read | Vise og hente kontakter. Kontakter knyttet til organisasjonskontoer og medlemmer med tilgang er utelukket. |
contacts.write | Validere og bruke oppdateringer eller opprettelser av kontakter. |
tasks.read | Vise og hente ikke-private oppgaver. |
tasks.write | Validere og bruke oppdateringer eller opprettelser av oppgaver. |
protocols.read | Vise og hente ikke-private protokoller. |
protocols.write | Validere og bruke oppdateringer eller opprettelser av protokoller. |
opportunities.read | Vise og hente muligheter. |
opportunities.write | Validere og bruke oppdateringer eller opprettelser av muligheter. |
projects.read | Vise og hente prosjekter. |
projects.write | Validere og bruke oppdateringer eller opprettelser av prosjekter og deltakere. |
milestones.read | Vise og hente prosjektmilepæler. |
milestones.write | Validere og bruke oppdateringer eller opprettelser av milepæler. |
members.read | Vise godkjente medlemmer, men bare med medlems-ID for Customer, bruker-ID og visningsnavn. |
events.read | Vise og hente hendelser og hovedkalendere. |
events.write | Validere og bruke oppdateringer eller opprettelser av hendelser. |
mails.read | Lese historikk over utgående e-post eid av organisasjonen, inkludert sendt og mislykket e-post. |
mail-drafts.read | Lese denne integrasjonens frittstående e-postutkast for godkjenning og leveringsstatus. |
mail-drafts.write | Forberede eller revidere e-postutkast for menneskelig godkjenning, men aldri godkjenne eller sende. |
tags.read | Finne tilgjengelige tagger for støttede enhetstyper. |
Private oppgaver og protokoller returneres aldri av dette API-et. Manglende omfang returnerer en autorisasjonsfeil; det behandles ikke som et tomt resultat.
En CRM-kontakt som ikke er medlem, kan leses og refereres til selv når kontakten er knyttet til en Scoutello-innlogging. Svaret inneholder bare organisasjonens CRM-felt, aldri identitets- eller tilgangsfelt for brukeren. Kontakter med rolle, tillatelser, invitasjon, godkjenning eller organisasjonskontostatus forblir skjult. Det er fortsatt ikke tillatt å redigere en kontakt som er knyttet til en innlogging (protected_contact), heller ikke CRM-felt som ellers ville vært uendret. Hvis en eksisterende, lesbar kontakt skal refereres fra en oppgave eller protokoll, kan contacts.write opprette den eksterne koblingen med bare externalId, scoutelloId og valgfri externalUpdatedAt. Senere oppdateringer av bare koblingsmetadata bruker externalId og valgfri externalUpdatedAt; utelat oppstartsverdien scoutelloId når koblingen er opprettet. Dette endrer aldri kontakten eller brukeren. Tildeling av godkjente medlemmer bruker den separate members.read-projeksjonen.
Nye nøkler bruker prefikset sctl_api_ og starter bare med contacts.write. Alle andre scopes krever et eksplisitt samtykke som en organisasjonsadministrator må gi ved opprettelse eller rotering av en nøkkel. Eksisterende legitimasjonsopplysninger beholder sine nåværende scopes og forblir gyldige.
Prosjektkoblede kontakter og e-postutkast
Kontaktopprettinger og -oppdateringer godtar valgfrie par med projectScoutelloId / projectExternalId og companyScoutelloId / companyExternalId (velg ett par). Kontakten, firmarelasjonen og prosjekttilhørigheten lagres atomisk for hvert element. For å legge til prosjekttilhørighet kreves projects.write; utelatte referanser bevarer andre relasjoner og tilhørigheter. Tilbakeleveringer av kontaktdetaljer inkluderer projectParticipations når projects.read er gitt. Agenter for salgsprosjekter må inkludere prosjektreferansen eksplisitt, også når en eksisterende kontakt brukes på nytt.
Frittstående utkast bruker det eksisterende systemet for menneskelig godkjenning, uten en arbeidsflytkjøring:
| Metode | Bane | Formål |
|---|---|---|
| GET | /mail-drafts | Paginerte utkast som eies av integrasjonen; valgfrie filtre for projectScoutelloId og status. |
| GET | /mail-drafts/{scoutelloId} | Gjeldende versjon, lenke for gjennomgang, innholdshash, status for godkjenning/utsending og eventuell e-post-ID. |
| GET | /mail-drafts/external/{externalId} | Slå opp en stabil ekstern integrasjons-ID. |
| POST | /mail-drafts/batch-upsert | Valider eller utfør klargjøring av utkastet. |
Klargjøring av utkast krever mail-drafts.write, contacts.read og projects.write. Den refererte kontakten blir deltaker i prosjektet. Godkjenneren må være et akseptert organisasjonsmedlem med tillatelse til å redigere e-post. Valg av avsender bruker de eksisterende tillatte organisasjons- eller personlige avsenderinnstillingene til dette medlemmet; vilkårlige From-adresser godtas ikke.
{
"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."
}
}]
}
Kontroller hvert valideringsresultat før gjentakelse med mode: "apply". Les den resulterende ID-en for å hente reviewUrl, draftVersion, contentHash, status, dispatchStatus og mailScoutelloId. Bruk expectedVersion: 0 bare ved opprettelse, og bruk den gjeldende returnerte versjonen ved revisjoner. Kontekst og godkjenner kan ikke endres; gjennomgåtte eller utsendte utkast avviser endret innhold. Identiske gjentakelser returnerer det opprinnelige utkastet.
Utkast vises i e-postfanene for prosjekter og kontakter og i dashbordets godkjenningsvarsler. API-forberedelse sender ingen e-post, heller ikke varsler; eksisterende oppførsel for arbeidsflytvarsler er uendret. Den ansvarlige personen kan redigere mottakere, emne, tekst og støttede vedlegg, lagre versjonen og velge Godkjenn og send. Integrasjoner kan ikke godkjenne eller sende. Mislykkede eller usikre leveranser skal aldri gjentas uten undersøkelse. Ved konvertering av protokollbaserte utkast skal protokollene bevares og erstatningene få gjensidige referanser.
MCP-tilgang
Den samme Scoutello API-nøkkelen og de samme omfangene kan brukes med MCP-endepunktet for streamable HTTP:
https://admin.scoutello.com/api/v1/mcp
Konfigurer MCP-klienten til å sende Authorization: Bearer YOUR_API_KEY. Den gamle URL-en /api/mcp beholdes som et kompatibilitetsalias, men nye klienter bør bruke det versjonerte endepunktet. Tidligere sctl_mcp_-legitimasjon godtas ikke; erstatt den med en integrasjonsnøkkel for Scoutello API.
MCP-verktøy følger REST-kontrakten direkte og bruker de samme kjøretidsskjemaene, organisasjonskontrollene, integrasjonslivssyklusen, hastighetsgrensene og tjenestemetodene. For eksempel tilsvarer contacts_list, contacts_get, contacts_get_by_external_id og contacts_batch_upsert de fire kontaktrutene. Det samme gjelder oppgaver, protokoller, salgsmuligheter, prosjekter, milepæler og arrangementer; e-post har mails_list og mails_get, medlemmer har members_list, og tagger har tags_list.
Serveren annonserer bare verktøy som tillates av gjeldende nøkkels omfang. En nøkkel med contacts.read kan finne kontaktleseverktøyene, men ikke contacts_batch_upsert; en nøkkel med contacts.write får verktøyet for batch-upsert, men ikke leseverktøyene. whoami er alltid tilgjengelig. Skriveverktøy har samme umiddelbare virkning som REST-versjonene. Bruk mode: "validate" for å kontrollere en batch uten å bruke den.
MCP er også ment for kommunikasjon mellom servere og tillater ikke nettlesertilgang på tvers av opprinnelser. JSON-RPC-transporten krever en egen URL, så MCP kan ikke dele URL med én REST-ressurs, selv om autentisering og dataoppførsel er identisk.
Veiledningen for MCP-integrasjon har fullstendige instrukser for klientkonfigurasjon, verifisering, verktøykoblinger og feilsøking.
Les oppføringer
Kontakter, oppgaver, protokoller, salgsmuligheter, prosjekter, milepæler og arrangementer bruker de samme leserutene:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
Erstatt contacts med tasks, protocols, opportunities, projects, milestones eller events for de andre synkroniseringsressursene. externalId vises i en lese-DTO når oppføringen er koblet av denne integrasjonen.
En listerespons har denne innpakningen:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit må være fra 1 til 100. Resultatene sorteres etter det effektive tidspunktet da den offentlige API-representasjonen deres ble endret, og deretter etter Scoutello-ID. Dette effektive tidspunktet kan være senere enn tidspunktet updatedAt for den returnerte entiteten når metadata for integrasjonskoblingen ble endret. Markører er ugjennomsiktige: lagre og send dem uendret, og ikke utled betydning fra innholdet.
Det første svaret fastsetter snapshotAt for denne gjennomgangen. Følg nextCursor til hasMore er false før en ny inkrementell lesing startes. Dette hindrer at poster som endres under paginering, gjør den pågående gjennomgangen ustabil.
Ved inkrementell synkronisering må alle markørsider behandles, og deretter må gjennomgangens snapshotAt lagres som tidsstempelet for siste synkronisering. Send det som ISO 8601-verdien updatedSince ved neste gjennomgang. Den nedre grensen er inklusiv, så et nytt forsøk på et fullført øyeblikksbilde kan returnere poster på grensen, men kan ikke hoppe over dem.
En respons for én post har denne innpakningen:
{
"data": {},
"requestId": "request-id"
}
Responser for én kontakt inkluderer også en relations-matrise. Hver relasjon beholder sin
Scoutello-relasjons-ID, opprettelsestidspunkt, type, notater samt connectedFrom- og
connectedTo-kontakthenvisninger. Kontakthenvisninger inneholder Scoutello-ID-en
og denne integrasjonens eksterne ID når en slik finnes. Kontakter som er ekskludert av
API-ets personvernbegrensning for organisasjonstilgang, eksponeres ikke gjennom relasjoner.
Responsen for kontaktlisten er kompakt og inkluderer ikke relasjoner; bruk
en av rutene for én kontakt når relasjonsdetaljer er nødvendige.
Arbeidsfiltre og markøromfang
Kontaktlister godtar search, type (person, company, supplier, other), status og tagIds. Søk trimmes, skiller ikke mellom små og store bokstaver og er begrenset til 200 tegn / 10 mellomromsseparerte token. Hvert token må forekomme i minst én av firstName, lastName eller companyName, inkludert eldre firmanavn som er lagret i lastName. Tegn som % og _ matches bokstavelig. Tagger bruker any-of-matching med 1–50 ID-er. Alle angitte filtre kombineres med AND. REST koder tagg-ID-er som gjentatte parametere; MCP leverer en matrise:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
Kontaktmarkører er bundet til organisasjonen, integrasjonen og hvert filter. Behold filtrene på hver side; endring av et filter avviser markøren. Rekkefølgen på tagger, duplikater og rekkefølgen, bokstavstørrelsen og mellomrommene i søketoken endrer ikke det effektive filteret.
Arbeidslisteruter godtar følgende ekstra filtre; andre kombinasjoner av ressurser og felt avvises:
| Ressurs | Filtre |
|---|---|
| Oppgaver | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Protokoller | projectScoutelloId, milestoneScoutelloId, status (draft eller final) |
| Muligheter | projectScoutelloId, stage, ownerScoutelloUserId |
| Prosjekter | status, assignedContactScoutelloId |
| Milepæler | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
dueBefore er eksklusiv; dueAfter er inklusiv. De sammenligner oppgavens forfallsdato eller milepælens sluttdato. Oppføringer uten denne datoen samsvarer ikke. Oppgi tidssonebevisste ISO-dato-tidspunkter. Alle filtre brukes før paginering. Fortsett en markør med nøyaktig de samme filtrene, inkludert updatedSince, og samme organisasjon/integrasjon. Sidestørrelsen kan endres. Gamle markører uten avgrensning må starte på nytt fra det lagrede høyvannstidspunktet etter denne lanseringen.
Prosjekter, milepæler, tildelinger og notater
GET /members (MCP members_list) bruker standardpaginering og krever members.read. Den returnerer scoutelloId (medlems-ID for Customer), scoutelloUserId (User-ID) og displayName. Bare godkjente organisasjonsmedlemmer med en rolle vises; oppslaget eksponerer ikke e-postadresser eller tillatelser.
Oppgaver godtar assignedScoutelloUserIds; muligheter bruker ownerScoutelloUserId. Prosjekter og milepæler bruker assignedContacts: [{"scoutelloId":"member-customer-id"}]. Tildelinger krever godkjente medlemmer av legitimasjonens organisasjon. Utelatte tildelinger forblir uendret; [] fjerner dem. Import av prosjekter, milepæler, oppgaver og protokoller skjer uten varsler: Det sendes ingen varsler eller annen kommunikasjon om tildelinger.
Hendelsen assignedContacts støtter lesbare CRM-kontakter og godkjente medlemmer angitt med medlems-ID for Customer. Godkjente medlemmer er fortsatt utilgjengelige som vanlige CRM-kontaktreferanser eller mål for eksterne lenker; bruk medlemsfeltet for tildeling av teamansvar.
Opprett milepæler med en name og enten projectScoutelloId eller projectExternalId. De støtter description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (standardverdi 0) og assignedContacts. Sluttdatoen kan ikke være tidligere enn startdatoen. Hver milepæl har en stabil ekstern lenke som er avgrenset til integrasjonen. Prosjektet kan ikke endres via API-et. Opprettelse og oppdatering lokaliserer navn og beskrivelse til organisasjonens språk.
Oppgaver og protokoller godtar prosjekt-, milepæl- og mulighetsreferanser som <entity>ScoutelloId eller <entity>ExternalId, for eksempel milestoneExternalId. Oppgi bare én skrivemåte per relasjon, også ved fjerning med null. Alle relasjoner må tilhøre legitimasjonens organisasjon. En referanse som bare angir milepæl, utleder prosjektet. Et motstridende prosjekt, eller eksplisitt fjerning av et prosjekt samtidig som milepælen beholdes, avvises. En koblet mulighet med et prosjekt må samsvare med arbeidets prosjekt. Utelatte relasjoner beholder gjeldende verdier. Eksplisitt null fjerner en relasjon når den gjenværende konteksten er gyldig. Leseresultater viser begge ID-skrivemåtene og oppgavetildelinger.
Oppgaveplanlegging og arbeidsflyter
Task status er den uforanderlige nøkkelen til en status i oppgavens effektive arbeidsflyt, ikke en fast enum. Les tilgjengelige arbeidsflyter for organisasjonen og prosjektet med GET /task-workflows ved å bruke omfanget tasks.read. Hver status inneholder nøkkelen, etiketten, livssyklusen type (backlog, unstarted, started, completed eller cancelled), farge, rekkefølge, standardindikator og arkivstatus. Prosjektoppføringer angir om organisasjonens arbeidsflyt er arvet. Konfigurasjon av arbeidsflyter administreres fortsatt i kontrollpanelet.
Oppgaver godtar nullable priority (low, medium, high eller urgent) og estimatedEffortMinutes, samt nullable startDate og dueDate. Lesing av oppgaver inkluderer den denormaliserte statusType, overordnet referanse, kompakte referanser til deloppgaver og referanser til blockedBy / blocks.
Opprett eller oppdater en underoppgave på ett nivå med enten parentTaskScoutelloId eller parentTaskExternalId; null gjør den til en oppgave på øverste nivå. Avhengigheter bruker matriser med { "scoutelloId": "..." }- eller { "externalId": "..." }-referanser i blockedBy og blocks. Utelatte relasjonsfelter bevarer dem, mens en tom avhengighetsmatrise fjerner avhengighetene i den retningen. API-et avviser nestede underoppgaver, avhengigheter mellom over- og underoppgaver, avhengigheter på tvers av organisasjoner, duplikater, selvreferanser og direkte eller transitive sykluser.
Filtre for oppgavelister godtar en eksakt arbeidsflytverdi status, en livssyklusverdi statusType, priority, parentState (top_level, subtask eller parent), og blockedState (blocked, blocking eller unblocked).
Protokoller godtar i tillegg status: "draft" | "final" (nye poster får som standard final). En ny protokoll krever type, date og enten en kontakt eller gyldig prosjekt-/milepælskontekst. contactExternalId: null fjerner kontakten bare når prosjekt-/milepælskonteksten fortsatt finnes. Interne prosjektnotater kan derfor opprettes og leses uten å finne på en kunde. Draft/final beskriver notatets status og sender aldri en melding. Private oppgaver og protokoller er fortsatt utilgjengelige.
Prosjektdeltakere
Prosjektets participants inneholder additive upserts med en contact-referanse som nøkkel, for eksempel:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
Deltakere beskriver potensielle kunder eller kunder som er knyttet til et prosjekt; ansvarlige medlemmer angis gjennom tildelinger. Utelatte deltakere, en tom matrise og utelatte deltakerfelter bevarer eksisterende data. null fjerner role, notes eller groupScoutelloId. Dupliserte kontakter som er løst i samme nyttelast, avvises. Grupper må allerede tilhøre det valgte prosjektet; leseresultater inkluderer participantGroups (ID/navn) samt deltaker-ID-er, kontakter, rolle, notater og gruppe-ID. Fjerning av deltakere eller opprettelse av grupper er for øyeblikket tilgjengelig i kontrollpanelet.
Batch-upsert av poster
Skriv opptil 100 poster med ressursens batch-rute:
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"
}
]
}
Oppgavebatcher finner oppgavepostene før overordnede oppgaver og avhengighetsrelasjoner brukes. Denne tofasers behandlingen gjør det mulig for en overordnet oppgave, en blokkerende oppgave eller en blokkert oppgave å referere til en annen oppgave som opprettes i samme batch, ved hjelp av den eksterne ID-en, uavhengig av postenes rekkefølge.
Bruk OpenAPI-dokumentet for feltene og valideringsbegrensningene til hver ressurs. Hver post må ha en stabil externalId på mellom 1 og 200 tegn. Behandle den som en ugjennomsiktig teknisk identifikator: Ikke bruk en e-postadresse, et navn, en API-hemmelighet eller andre personopplysninger. externalUpdatedAt er valgfritt, men anbefales sterkt når kildesystemet oppgir et pålitelig tidspunkt for endring.
Forespørselsbrødteksten er begrenset til 1 MiB. mode har standardverdien apply:
applyvaliderer og skriver godkjente poster.validateutfører den samme valideringen og sammenkoblingen uten å skrive, og returnererwould_*-resultater.
For kontaktimporter kan matchByEmail settes til true i forespørselen. Standardverdien er false; ekstern ID er den sikrere identitetsavgrensningen.
Utelatte felt beholder den nåværende verdien. En eksplisitt null tømmer et felt som kan ha nullverdi, og en oppgitt tom tilordnings-/taggmatrise tømmer denne relasjonen. Prosjektets participants er additive upserts: En tom matrise lar deltakerlisten være uendret. Skriving av tagger for kontakter, oppgaver, muligheter og hendelser bruker Scoutello-taggers ID-er. Eksterne ID-er for relasjoner slås bare opp gjennom lenker som tilhører den gjeldende integrasjonen, mens Scoutello-bruker-ID-er som brukes til eierskap eller ansvar, må identifisere godkjente medlemmer av den gjeldende organisasjonen.
Opprettelse av muligheter krever en konto eller kontakt, og tapte muligheter krever en tapsårsak. Pengebeløp bruker heltall i cent. Prosjekt- og hendelsesnavn og -beskrivelser leses og skrives på organisasjonens konfigurerte språk. Hendelsesskriving støtter eksplisitte datoer og daglig, ukentlig eller månedlig gjentakelse med unntak; publiserte synlighetsnivåer er fortsatt underlagt Scoutellos juridiske klargjøringskrav. API-et eksponerer ikke billettsalg til hendelser, deltakere, medier, maler, nyhetsbrev, samarbeid eller andre avanserte funksjoner for hendelsesadministrasjon.
Oppdage tagger
Bruk taggendepunktet før tagIds oppgis:
GET /tags?entity=events&type=category
entity er obligatorisk og godtar contacts, tasks, opportunities eller events. Dette tilordnes den tilsvarende lagrede taggrelevansen. type er valgfritt og godtar category eller attribute. Valgbare kategorier kan eies av organisasjonen eller være globale; valgbare attributter kommer fra Scoutellos kuraterte globale attributtsett. Resultatene inkluderer scoutelloId, navnet lokalisert til organisasjonens språk, type og relevancy. Tagg-ID-er på tvers av organisasjoner, med feil relevans eller som ikke kan velges, avviser det berørte gruppeelementet.
Lese historikk for utgående e-post
Posthistorikk for e-post er skrivebeskyttet:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Kun e-post som eies av organisasjonen, med status sent eller failed, returneres. Svarene inneholder vanlige lagrede topptekster og brødtekst, BCC, status og tidsstempler, referanser til prosjekter/hendelser/nyhetsbrev, ID-er og typer for vedlegg samt aggregerte statistikker for levering, åpning, klikk, avvisninger, klager og avslag blant mottakere. Kladd, e-post i kø eller planlagt e-post, rader per mottaker, gjengitte øyeblikksbilder, rå leverandørfeil og URL-er for nedlasting av vedlegg eksponeres aldri. En senere oppdatering av mottakerleveringen oppdaterer e-postens effektive synkroniseringstidspunkt, slik at e-posten vises igjen i inkrementelle lesinger. Det finnes ingen ruter for skriving av e-post.
Et resultat av en utføring kan være created, updated, linked, unchanged, stale_ignored eller rejected. Valideringen bruker would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale eller rejected. En gyldig batchforespørsel returnerer HTTP 200 selv når enkeltposter avvises. Kontroller derfor alltid hvert element og sammendraget i svaret. Ta vare på svaret requestId når Scoutello-supporten skal undersøke en feil.
Tidsstempler og konflikter
Når externalUpdatedAt er angitt, bruker Scoutello den til å avvise foreldede endringer uten å avvise resten av batchen. Et resultat av typen stale_ignored er endelig for den eldre nyttelasten. Hent den gjeldende posten før det avgjøres om en nyere versjon skal sendes.
Behandle tidsstempler som UTC ISO 8601-verdier. Bevar den opprinnelige presisjonen, og ikke erstatt tidspunktet for når en synkroniseringsjobb ble kjørt med kilderecordens endringstidspunkt.
Idempotens
Idempotensgrensen er integrasjonen pluss externalId. Scoutello sammenligner en kanonisk hash av nyttelasten og den valgfrie verdien externalUpdatedAt. Dermed oppretter nye forsøk på samme post ikke duplikater og kan returnere unchanged.
Med externalUpdatedAt er samme tidsstempel og nyttelast unchanged, et eldre tidsstempel er stale_ignored, og samme tidsstempel med en annen nyttelast er en versjonskonflikt. For en kobling som aldri har godtatt et tidsstempel, forblir den samme nyttelasten uten tidsstempel unchanged, mens en endret nyttelast brukes i mottaksrekkefølge. Etter at en kobling har godtatt et tidsstempel, avvises en endret nyttelast som utelater externalUpdatedAt, som en versjonskonflikt. Uversjonerte data kan dermed ikke overskrive versjonert tilstand. Derfor anbefales det på det sterkeste å bruke kildens endringstidspunkter.
Revisjonsspor
Godkjente API-opprettelser, -oppdateringer og synkroniseringshandlinger som bare oppretter koblinger, vises i Scoutello-endringslogger med Public API som kilde og knyttes til den ansvarlige integrasjonen. Operasjonelle kjøringssammendrag beholder forespørsels-ID-er og aggregerte resultatantall for feilsøking. De beholder ikke dataposter eller API-hemmeligheter.
Feil og nye forsøk
Feil på forespørselsnivå bruker denne strukturen:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
Prøv HTTP 429- og midlertidige 5xx-svar på nytt med eksponentiell tilbakeventing og jitter. Respekter Retry-After når den finnes. Nettverksfeil kan ha oppstått etter at Scoutello godtok en forespørsel. Det er trygt å sende samme batch på nytt, fordi hver post er idempotent basert på ekstern ID og kanonisk nyttelast. Ikke prøv automatisk på nytt ved autentiserings-, autorisasjons-, validerings- eller versjonskonfliktfeil, eller ved individuelle rejected-resultater, uten å endre forespørselen.
Anbefalt løkke for toveissynkronisering
- Kall
/whoamiunder oppsettet, og bekreft forventet organisasjon og tilgangsomfang. - Les hver side som er endret siden det siste fullførte høyvannsnivået, og bruk endringene idempotent i det eksterne systemet.
- Send eksterne endringer til
/batch-upsertved å bruke stabile eksterne ID-er og tidsstempler for kildeendring. - Lagre kontrollpunkter først etter at alle sider og resultater for enkeltelementer er behandlet.
- Løs konflikter i henhold til eierskapsreglene i kildesystemet. Ikke etterlign sletting ved å sende tomme poster.
Scoutello tilbyr med hensikt ingen offentlig slettingsrute i denne første versjonen. Håndter slettings- eller arkiveringsregler utenfor API-et frem til en dokumentert livssyklusoperasjon innføres.
Sosiale innlegg for menneskelig gjennomgang
Det sosiale API-et klargjør innlegg for en navngitt person som skal gjennomgå dem. Det kan ikke godkjenne eller publisere innleggene. REST og MCP bruker de samme tilgangsomfangene og den samme tjenesten.
| Omfang | Endepunkter under /api/v1 |
|---|---|
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 |
Nye tilgangsomfang må tildeles eksplisitt. Eksisterende legitimasjon får ingen ekstra tilgang. Bruk members.read for å finne bruker-ID-er for medlemmer, og velg en person som skal gjennomgå innlegget, med publiseringstillatelse (newsletter.edit). Utkast krever ikke en CRM-kontakt eller et prosjekt.
{
"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"]
}]
}
}]
}
Bruk publishMode: "now" og scheduledAt: null for publisering etter
godkjenning. Hver kanalvariant inneholder full tekst, innstillinger og
ordnede medie-ID-er. Kanaloppdagelse returnerer støttede formater, grenser og
innstillinger. LinkedIn-profiler/-sider, Facebook, Instagram og Threads støttes
nå. Instagram krever medier. Én variant kan ha opptil ti bilder eller videoer.
Batcher godtar opptil 100 unike eksterne ID-er innenfor den eksisterende
forespørselsgrensen på 1 MiB. mode: "validate" kontrollerer referanser og
versjoner uten å lagre utkast, laste opp ressurser, opprette varsler eller legge
arbeid i kø. Anvendelsesresultater inneholder ID-er, gjennomgangslenker,
versjoner og resultater per oppføring. Delvise feil ruller ikke tilbake vellykkede
oppføringer. Varslingsfeil returnerer en advarsel og den lagrede gjennomgangs-URL-en.
Hent gjeldende draftVersion før et ventende utkast revideres. Identiske
gjentakelser er idempotente og bevarer senere menneskelige endringer. Personen
som skal gjennomgå utkastet, kan ikke byttes i det samme utkastet. Etter
godkjenning eller avvisning skal et nytt forslag bruke en ny ekstern ID. Utkast
kan bare leses av den kallende integrasjonen. Publiseringshistorikken omfatter
alle varige Scoutello-opprettede kampanjer i organisasjonen, inkludert innlegg fra
dashbordet, skript og eldre Scoutello-innlegg. Ekstern kanalhistorikk importeres ikke.
Lister bruker standardparameterne limit , cursor og updatedSince
. Innlegg og utkast godtar også channelId , status , after ,
before og search ; behold alle filtre på påfølgende markørsider.
Datofiltre gjelder publiseringstidspunktet, eller
opprettelsestidspunktet for ventende utkast med umiddelbar publisering.
Utkastets status filtrerer godkjenningsstatus; innleggets status
samsvarer med kampanjens eller kanalens leveringsstatus. Lesing gir sist
kjente leveringsstatus, feil per kanal, offentlige lenker og tidsstempler for
avstemming. Inkrementell utkastlesing gjenspeiler også endringer i kampanjelevering.
Last opp medier
- Kall
POST /social-media/uploadsmedclientUploadId,filename,contentType,sizei byteformat og små heksadesimalesha256for de opprinnelige bytene. Støttede typer er PNG, JPEG, WebP, MP4, WebM, QuickTime og M4V. Opplastingsgrensen er 500 MiB. - Send de opprinnelige bytene med HTTP
PUTtil den returnerteupload.url, med topptekstene. Opplastings-URL-er utløper etter 15 minutter. BrukclientUploadIdpå nytt ved nye forsøk med samme fil; utløpte økter eller andre filer krever en ny ID. - Kall
POST /social-media/uploads/{assetId}/finalizemed et JSON-innhold på{}. Ferdigstillingen kontrollerer størrelse, type, signatur og kontrollsum, låser en privat kopi og returnerer ressurs-ID-en formediaIds. Gjentatt ferdigstilling er trygt.
Eierskap til opplastingen er knyttet til organisasjonen og integrasjonen. Utkast kan referere til ferdigstilte ressurser fra organisasjonen. Forhåndsvisnings-URL-er er midlertidige; hent utkastet på nytt for å oppdatere dem. Opplastings-URL-er utstedes aldri for ferdigstilte objekter.
Menneskelig gjennomgang og publisering
Den som skal gjennomgå innholdet, mottar et varsel i kontrollpanelet og kan åpne innlegget fra Postings eller via gjennomgangs-URL-en. Redigering oppretter en ny uforanderlig versjon. Godkjenning bruker den viste versjonen og innholdshashen, kontrollerer medlemskap, kanaler og ressurser på nytt, og oppretter atomisk én varig kampanje. Hvis det foreslåtte tidspunktet er passert, må den som gjennomgår innholdet, lagre et uttrykkelig nytt tidspunkt eller velge publisering ved godkjenning.
Nye forsøk i køen bruker kampanjen og plattformskvitteringene til den på nytt. Godkjente kampanjer kan ikke redigeres direkte. Avbryting via kontrollpanelet bevarer godkjenningshistorikken og mediene; avbryting kan ikke stanse en aktiv utsendelse. Hent utkastet eller kampanjen for å skille mellom godkjenning og faktisk levering på plattformen.