Hop til hovedindhold

Scoutello API

Scoutello API'et er et server-til-server-API til synkronisering af en organisations kontakter, opgaver, protokoller, muligheder, projekter, milepæle og begivenheder i begge retninger. Det giver også skrivebeskyttet adgang til historik over udgående mails, opslag af medlemmer, der kan tildeles, samt opdagelse af entitetsbevidste tags. Inkrementelle GET/list-ruter og idempotente batchopdateringer er synkroniseringsprimitiverne i denne version. API'et understøtter ikke sletninger eller webhooks.

API'ets basis-URL er:

https://admin.scoutello.com/api/v1

Den vises også under Organisationsindstillinger → Udvikler/API. OpenAPI-dokumentet findes på:

https://admin.scoutello.com/api/v1/openapi.json

Opret og beskyt en nøgle​

For modulære organisationer skal CRM-modulet være aktivt ud over nøglens påkrævede scopes. En gyldig nøgle kan ikke aktivere et manglende modul. Anmodninger returnerer HTTP 403 med fejlkoden module_not_active, når CRM-adgang ikke er tilgængelig. En organisationsadministrator kan gennemgå eller aktivere CRM under Abonnement; prøv igen, når adgangen er aktiv.

En organisationsadministrator kan oprette en integration og en API-nøgle under Organisationsindstillinger → Udvikler/API. Den komplette nøgle vises én gang. Kopiér den til en secret manager, før dialogboksen lukkes; Scoutello kan ikke vise den komplette nøgle igen.

  • Brug en separat integration og nøgle til hvert eksternt system og miljø.
  • Giv kun de scopes, som systemet har brug for.
  • Læg aldrig en nøgle i browserkode, en URL, kildekontrol, logs, supportbeskeder eller klientsidelagring.
  • Rotér nøgler efter en fast plan. Når en aktiv integration roteres, virker erstatningsnøglen med det samme, og den tidligere nøgle forbliver gyldig i højst 15 minutter, så det eksterne system kan skifte uden nedetid. En tidligere udløbsdato gælder stadig, så den tidligere nøgle kan holde op med at virke tidligere.
  • Hvis en nøgle kan være blevet eksponeret, skal integrationen sættes på pause, før nøglen roteres. En pause afviser midlertidigt alle integrationens nøgler. En rotation, mens integrationen er sat på pause, har intet overlap: Den tidligere nøgle forbliver deaktiveret, og erstatningsnøglen forbliver deaktiveret, indtil integrationen genoptages.
  • Tilbagekald hele integrationen permanent, når et eksternt system frakobles. Tilbagekaldelse deaktiverer alle dens nøgler og kan ikke fortrydes.

Send nøglen med hver godkendte anmodning:

Authorization: Bearer YOUR_API_KEY

Bearer-godkendelse foretrækkes. Klienter, der ikke kan angive Authorization, kan i stedet bruge x-api-key. Send ikke begge headere; anmodninger med forskellige værdier i de to headere afvises.

API'et er beregnet til backend-klienter og aktiverer ikke browseradgang på tværs af oprindelser.

Brug GET /whoami efter konfiguration af en nøgle for at kontrollere integrationen, organisationen, scopes og nøglebegrænsningerne uden at hente personlige brugerdata.

Scopes​

OmrådeGiver mulighed for
contacts.readListe og hente kontakter. Kontakter til organisationskonti og medlemmer med adgang er udelukket.
contacts.writeValidere og anvende opdateringer eller oprettelser af kontakter.
tasks.readListe og hente ikke-private opgaver.
tasks.writeValidere og anvende opdateringer eller oprettelser af opgaver.
protocols.readListe og hente ikke-private protokoller.
protocols.writeValidere og anvende opdateringer eller oprettelser af protokoller.
opportunities.readListe og hente muligheder.
opportunities.writeValidere og anvende opdateringer eller oprettelser af muligheder.
projects.readListe og hente projekter.
projects.writeValidere og anvende opdateringer eller oprettelser af projekter og deltagere.
milestones.readListe og hente projektmilepæle.
milestones.writeValidere og anvende opdateringer eller oprettelser af milepæle.
members.readListe accepterede medlemmer med kun medlemmets Customer ID, User ID og viste navn.
events.readListe og hente begivenheder og centrale tidsplaner.
events.writeValidere og anvende opdateringer eller oprettelser af begivenheder.
mails.readLæse historikken over udgående mails, der ejes af organisationen, og som er sendt eller mislykkedes.
mail-drafts.readLæse denne integrations selvstændige kladder til e-mailgodkendelse og leveringsstatus.
mail-drafts.writeForberede eller redigere e-mailkladder til menneskelig godkendelse; aldrig godkende eller sende.
tags.readFinde valgbare tags for understøttede enhedstyper.

Private opgaver og protokoller returneres aldrig af denne API. Hvis et område mangler, returneres en autorisationsfejl; det behandles ikke som et tomt resultat.

En CRM-kontakt, der ikke er medlem, kan læses og refereres, selv når den er knyttet til et Scoutello-login. Svaret indeholder kun organisationens CRM-felter og aldrig brugeridentitet eller adgangsfelter. Kontakter med en rolle, tilladelser, invitation, accept eller organisationskontostatus forbliver skjulte. Det er fortsat ikke tilladt at redigere en login-tilknyttet kontakt (protected_contact), heller ikke felter, der ellers er uændrede i CRM'et. Hvis en eksisterende, læsbar kontakt skal refereres fra en opgave eller protokol, kan contacts.write etablere dens eksterne forbindelse med kun externalId, scoutelloId og eventuelt externalUpdatedAt. Senere opdateringer, der kun ændrer forbindelsesmetadata, bruger externalId og eventuelt externalUpdatedAt; udelad scoutelloId efter oprettelsen af forbindelsen. Dette ændrer aldrig kontakten eller den tilknyttede bruger. Tildeling af accepterede medlemmer bruger den separate members.read-projektion.

Nye nøgler bruger præfikset sctl_api_ og starter kun med contacts.write. Alle andre scopes kræver et eksplicit tilvalg, som en organisationsadministrator skal give ved oprettelse eller rotation af en nøgle. Eksisterende legitimationsoplysninger beholder deres nuværende scopes og forbliver gyldige.

Projektforbundne kontakter og e-mailkladder​

Kontaktopdateringer accepterer valgfrie par med projectScoutelloId / projectExternalId og companyScoutelloId / companyExternalId (vælg ét fra hvert par). Kontakten, virksomhedsrelationen og projekttilknytningen gemmes atomisk pr. element. Tilføjelse af projekttilknytning kræver projects.write; udeladte referencer bevarer andre relationer og tilknytninger. Tilbagemeldinger med kontaktoplysninger inkluderer projectParticipations, når projects.read er tildelt. Agenter for salgsprojekter skal udtrykkeligt inkludere projektreferencen, også når en kontakt genbruges.

Selvstændige kladder bruger det eksisterende system til menneskelig godkendelse uden en workflowkørsel:

MetodeStiFormål
GET/mail-draftsPaginering af integrationsstyrede kladder; valgfrie projectScoutelloId- og status-filtre.
GET/mail-drafts/{scoutelloId}Aktuel version, gennemgangslink, indholdshash, status for godkendelse/afsendelse og eventuelt mail-id.
GET/mail-drafts/external/{externalId}Slå et stabilt eksternt integrations-id op.
POST/mail-drafts/batch-upsertValidér eller anvend klargøring af kladden.

Klargøring af kladden kræver mail-drafts.write, contacts.read og projects.write. Den refererede kontakt bliver deltager i projektet. Godkenderen skal være et accepteret organisationsmedlem med tilladelse til at redigere e-mails. Valg af afsender bruger dette medlems eksisterende tilladte organisations- eller personlige afsenderindstillinger; vilkårlige Fra-adresser accepteres 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."
}
}]
}

Gennemgå hvert valideringsresultat, før du gentager med mode: "apply". Læs det resulterende id for at hente reviewUrl, draftVersion, contentHash, status, dispatchStatus og mailScoutelloId. Brug kun expectedVersion: 0 til oprettelse og den aktuelt returnerede version til revisioner. Kontekst og godkender kan ikke ændres; gennemgåede eller afsendte kladder afviser ændret indhold. Identiske gentagelser returnerer den oprindelige kladde.

Kladder vises under projektets/kontaktens faner for e-mails samt i dashboardets godkendelsesnotifikationer. API-forberedelse sender ingen e-mails, heller ikke notifikationsmails; den eksisterende adfærd for workflow-notifikationsmails er uændret. Den ansvarlige person kan redigere modtagere, emne, brødtekst og understøttede vedhæftede filer, gemme versionen og derefter Approve & send. Integrationer kan ikke godkende eller sende. Mislykket eller tvetydig levering forsøges aldrig blindt igen. Ved konvertering af protokolbaserede kladder skal protokollerne bevares, og deres erstatninger skal krydsrefereres.

MCP-adgang​

Den samme Scoutello API-nøgle og de samme scopes kan bruges sammen med MCP-endpointet til streambar HTTP:

https://admin.scoutello.com/api/v1/mcp

Konfigurer MCP-klienten til at sende Authorization: Bearer YOUR_API_KEY. Den ældre /api/mcp-URL forbliver et sti-kompatibilitetsalias, men nye klienter bør bruge det versionsinddelte endpoint. Tidligere sctl_mcp_-legitimationsoplysninger accepteres ikke; erstat dem med en Scoutello API-integrationsnøgle.

MCP-værktøjer svarer direkte til REST-kontrakten og bruger de samme runtime-skemaer, lejerkontroller, integrationslivscyklus, hastighedsbegrænsning og tjenestemetoder. Eksempelvis afspejler contacts_list, contacts_get, contacts_get_by_external_id og contacts_batch_upsert de fire kontaktruter. Det samme mønster gælder for opgaver, protokoller, muligheder, projekter, milepæle og begivenheder; mail eksponerer mails_list og mails_get, medlemmer eksponerer members_list, mens tags eksponerer tags_list.

Serveren annoncerer kun værktøjer, der er tilladt af den aktuelle nøgles scopes. En nøgle med contacts.read kan finde værktøjerne til læsning af kontakter, men ikke contacts_batch_upsert; en nøgle med contacts.write får batch-upsert-værktøjet, men ikke læseværktøjerne. whoami er altid tilgængelig. Skriveværktøjer har de samme øjeblikkelige effekter som deres REST-modstykker, så brug mode: "validate", når en kaldende part skal inspicere en batch uden at anvende den.

MCP fungerer også server-til-server og aktiverer ikke adgang på tværs af oprindelser fra browsere. Dets JSON-RPC-transport kræver en dedikeret URL, så den kan ikke dele en individuel REST-ressource-URL, selv om godkendelse og dataadfærd er fælles.

Se MCP-integrationsvejledningen for komplet konfiguration af klienten samt instruktioner i verificering, værktøjstilknytning og fejlfinding.

Læs poster​

Kontakter, opgaver, protokoller, muligheder, projekter, milepæle og begivenheder bruger de samme læseruter:

GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}

Erstat contacts med tasks, protocols, opportunities, projects, milestones eller events for de øvrige synkroniseringsressourcer. externalId vises i en læse-DTO, når posten er blevet knyttet af denne integration.

Et listesvar har denne kuverten:

{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}

limit skal være fra 1 til 100. Resultatene sorteres etter det effektive tidspunktet da deres offentlige API-representasjon ble endret, og deretter etter Scoutello-ID. Dette effektive tidspunktet kan være senere enn tidspunktet for den returnerte entiteten updatedAt når metadata for integrasjonskoblingen ble endret. Markører er ugjennomsiktige: lagre og send dem uendret, og ikke tolk 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 pagineringen, gjør den pågående gjennomgangen ustabil.

Ved inkrementell synkronisering skal alle sider med markører behandles, og deretter skal gjennomgangens snapshotAt lagres som tidsstempelet for høyeste vannstand. Send det som ISO 8601-verdien updatedSince ved neste gjennomgang. Den nedre grensen er inklusiv, så en ny kjøring av et fullført øyeblikksbilde kan returnere poster på grensen, men kan ikke hoppe over dem.

Et svar for én post har denne kuverten:

{
"data": {},
"requestId": "request-id"
}

Svar for én kontakt inkluderer også en relations-matrise. Hver relasjon beholder sin Scoutello-relasjons-ID, opprettelsestidspunkt, type, notater samt connectedFrom- og connectedTo-kontaktreferansene. Kontaktreferanser inneholder Scoutello-ID-en og denne integrasjonens eksterne ID når en slik finnes. Kontakter som er utelatt av API-ets personvernbegrensning for organisasjonstilgang, eksponeres ikke gjennom relasjoner. Kontaktsvaret for lister 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øket trimmes, skiller ikke mellom store og små 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 lagret i lastName. Tegn som % og _ samsvarer bokstavelig. Tagger bruker samsvar med én vilkårlig verdi og støtter 1–50 ID-er. Alle angitte filtre kombineres med AND. REST koder tagg-ID-er som gjentatte parametere, mens 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 alle filtre. Behold filtrene på hver side; endring av et filter avviser markøren. Rekkefølgen og duplikater i tagger samt rekkefølgen, store og små bokstaver og mellomrom i søketoken endrer ikke det effektive filteret.

Arbejdslistens ruter accepterer følgende ekstra filtre; andre kombinationer af ressourcer og felter afvises:

RessourceFiltre
OpgaverprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtokollerprojectScoutelloId, milestoneScoutelloId, status (draft eller final)
MulighederprojectScoutelloId, stage, ownerScoutelloUserId
Projekterstatus, assignedContactScoutelloId
MilepæleprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore er eksklusiv; dueAfter er inklusiv. De sammenligner opgavens forfaldsdato eller milepælens slutdato; poster uden denne dato matcher ikke. Angiv ISO-dato- og -klokkeslæt med tidszone. Alle filtre anvendes før sideinddeling. Fortsæt en cursor med præcis de samme filtre, herunder updatedSince, og den samme organisation/integration. Sidestørrelsen kan ændres. Gamle cursorer uden scope skal efter denne udgivelse starte forfra fra det gemte high-water-tidspunkt.

Projekter, milepæle, tildelinger og noter​

GET /members (MCP members_list) bruger standard-sideinddeling og kræver members.read. Den returnerer scoutelloId (medlemmet Customer-ID), scoutelloUserId (User-ID) og displayName. Kun godkendte organisationsmedlemmer med en rolle vises; opslaget viser ikke e-mailadresser eller tilladelser.

Opgaver accepterer assignedScoutelloUserIds; muligheder bruger ownerScoutelloUserId. Projekter og milepæle bruger assignedContacts: [{"scoutelloId":"member-customer-id"}]. Tildelinger kræver godkendte medlemmer af legitimationsoplysningernes organisation. Udeladte tildelinger forbliver uændrede; [] rydder dem. Import af projekter, milepæle, opgaver og protokoller sker uden notifikationer: Der sendes ingen tildelingsnotifikationer eller anden kommunikation.

Hændelsen assignedContacts understøtter CRM-kontakter, der kan læses, samt godkendte medlemmer angivet via medlemmets Customer-ID. Godkendte medlemmer kan ikke bruges som almindelige CRM-kontakthenvisninger eller mål for eksterne links; brug medlemsfeltet for teamansvar.

Opret milepæle med en name og enten projectScoutelloId eller projectExternalId. De understøtter description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (standardværdien er 0) og assignedContacts. Slutdatoer kan ikke ligge før startdatoerne. Hver milepæl har et stabilt eksternt link, der er afgrænset til integrationen. Dens projekt kan ikke ændres via API'et. Oprettelse og opdatering lokaliserer navn og beskrivelse til organisationens sprog.

Opgaver og protokoller accepterer projekt-, milepæls- og mulighedsreferencer som <entity>ScoutelloId eller <entity>ExternalId, f.eks. milestoneExternalId. Angiv kun én stavemåde pr. relation, også ved rydning med null. Alle relationer skal tilhøre legitimationsoplysningernes organisation. En reference, der kun angiver en milepæl, udleder projektet. Et modstridende projekt eller eksplicit rydning af et projekt, mens dets milepæl bevares, afvises. En tilknyttet mulighed med et projekt skal stemme overens med arbejdets projekt. Udeladte relationer bevarer de aktuelle værdier; eksplicit null rydder en relation, når den resterende kontekst er gyldig. Læsninger viser begge ID-stavemåder og opgavetilknytninger.

Opgaveplanlægning og arbejdsgange​

Task status er den uforanderlige nøgle for en status i opgavens effektive arbejdsgang, ikke en fast enum. Læs organisationens og projekternes tilgængelige arbejdsgange med GET /task-workflows ved hjælp af tasks.read-omfanget. Hver status omfatter dens nøgle, etiket, livscyklus- type (backlog, unstarted, started, completed eller cancelled), farve, rækkefølge, standardflag og arkivstatus. Projektposter angiver, om organisationens arbejdsgang nedarves. Konfiguration af arbejdsgange administreres fortsat i dashboardet.

Opgaver accepterer nullable priority (low, medium, high eller urgent) og estimatedEffortMinutes samt nullable startDate og dueDate. Opgavelæsninger omfatter den denormaliserede statusType, en reference til den overordnede opgave, kompakte referencer til underopgaver samt blockedBy-/blocks-referencer.

Opret eller opdatér en underopgave på ét niveau med enten parentTaskScoutelloId eller parentTaskExternalId; null gør den til en topniveauopgave. Afhængigheder bruger arrays med { "scoutelloId": "..." }- eller { "externalId": "..." }-referencer i blockedBy og blocks. Udeladte relationsfelter bevarer de eksisterende værdier, mens et tomt afhængighedsarray rydder den pågældende retning. API'et afviser indlejrede underopgaver, afhængigheder mellem forælder og barn, afhængigheder på tværs af organisationer, dubletter, selvreferencer samt direkte eller transitive cyklusser.

Filtre for opgavelister accepterer et nøjagtigt workflow-status, en livscyklus-statusType, priority, parentState (top_level, subtask eller parent) samt blockedState (blocked, blocking eller unblocked).

Protokoller accepterer desuden status: "draft" | "final" (nye poster bruger som standard final). En ny protokol kræver type, date og enten en kontakt eller en gyldig projekt-/milepælskontekst. contactExternalId: null rydder kun kontakten, når projekt-/milepælskonteksten stadig er angivet. Interne projektnoter kan derfor oprettes og læses uden at opfinde en kunde. Kladde/færdig beskriver notens status og sender aldrig en kommunikation. Private opgaver og protokoller forbliver utilgængelige.

Projektdeltagere​

Projektets participants indeholder additive upserts, der identificeres via en contact-reference, f.eks.:

{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}

Deltagere beskriver potentielle eller eksisterende kunder, der er knyttet til et projekt; ansvarlige teammedlemmer angives via assignments. Udeladte deltagere, et tomt array og udeladte deltagerfelter bevarer de eksisterende data. null rydder role, notes eller groupScoutelloId. Dublerede løste kontakter i samme payload afvises. Grupper skal allerede være tilknyttet det valgte projekt; læsninger omfatter participantGroups (ID/navn) samt deltager-ID'er, kontakter, rolle, noter og gruppe-ID. Fjernelse af deltagere eller oprettelse af grupper er i øjeblikket tilgængelig i dashboardet.

Batchoprettelse eller -opdatering af poster​

Skriv op til 100 poster via ressourcens batchroute:

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"
}
]
}

Opgavebatcher finder opgaveposterne, før relationer mellem forældre og afhængigheder anvendes. Denne behandling i to faser gør det muligt for en forælder, en blokerende opgave eller en blokeret opgave at referere til en anden opgave, der oprettes i samme batch, via dens eksterne ID, uanset posternes rækkefølge.

Brug OpenAPI-dokumentet til at finde felter og valideringsbegrænsninger for hver ressource. Hver post skal have en stabil externalId på mellem 1 og 200 tegn. Behandl den som en uigennemsigtig teknisk identifikator: Brug ikke en e-mailadresse, et navn, en API-hemmelighed eller andre personoplysninger. externalUpdatedAt er valgfri, men anbefales kraftigt, når kildesystemet leverer et pålideligt ændringstidspunkt.

Anmodningens brødtekst er begrænset til 1 MiB. mode har som standard værdien apply:

  • apply validerer og skriver accepterede poster.
  • validate udfører den samme validering og matchning uden at skrive og returnerer resultater for would_*.

Ved kontaktimport kan matchByEmail sættes til true i anmodningen. Standardværdien er false; eksternt ID er den sikrere identitetsgrænse.

Udeladte felter bevarer den aktuelle værdi. Et eksplicit null rydder et nullbart felt, og et angivet tomt array med tildelinger eller tags rydder den pågældende relation. Projekt- participants er additive upserts: Et tomt array ændrer ikke deltagerlisten. Skrivning af tags for kontakter, opgaver, muligheder og begivenheder bruger Scoutello-tag-ID'er. Eksterne ID'er for relationer slås kun op via links, der tilhører den aktuelle integration, mens Scoutello-bruger-ID'er, der bruges til ejerskab eller ansvar, skal identificere accepterede medlemmer af den aktuelle organisation.

Ved oprettelse af muligheder kræves en konto eller kontakt, og tabte muligheder kræver en tabsårsag. Beløb angives i hele cent. Projekt- og begivenhedsnavne samt beskrivelser læses og skrives på organisationens konfigurerede sprog. Skrivning af begivenheder understøtter eksplicitte datoer samt daglig, ugentlig eller månedlig gentagelse med undtagelser; offentliggjorte synlighedsniveauer er fortsat underlagt Scoutellos juridiske krav for offentliggørelse. API'et giver ikke adgang til billetsalg, deltagere, medier, skabeloner, nyhedsbreve, samarbejder eller andre avancerede funktioner til begivenhedsstyring.

Find tags​

Brug tags-endpointet, før tagIds angives:

GET /tags?entity=events&type=category

entity er påkrævet og accepterer contacts, tasks, opportunities eller events. Det knyttes til den tilsvarende gemte tagrelevans. type er valgfri og accepterer category eller attribute. Valgbare kategorier kan være organisationsejede eller globale; valgbare attributter kommer fra Scoutellos kuraterede globale attributsæt. Resultaterne indeholder scoutelloId, navnet lokaliseret til organisationens sprog, type og relevancy. Tags på tværs af organisationer, tags med forkert relevans og tags, der ikke kan vælges, afviser det berørte batchelement.

Læs historik over udgående mail​

Mailhistorik er skrivebeskyttet:

GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}

Der returneres kun organisations-ejet mail med status sent eller failed. Svarene indeholder almindelige gemte headers og brødtekst, BCC, status og tidsstempler, referencer til projekter/events/nyhedsbreve, id'er og typer for vedhæftede filer samt samlede statistikker for modtagerlevering, åbninger, klik, bounces, klager og afvisninger. Kladder, mail i kø eller planlagt mail, rækker pr. modtager, gengivne snapshots, rå fejl fra udbyderen og URL'er til download af vedhæftede filer eksponeres aldrig. En senere opdatering af modtagerleveringen fremrykker mailens effektive synkroniseringstidsstempel, så mailen vises igen ved inkrementelle læsninger. Der findes ingen mail-skriveruter.

Et anvendelsesresultat kan være created, updated, linked, unchanged, stale_ignored eller rejected. Valideringen bruger would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale eller rejected. En gyldig batchanmodning returnerer HTTP 200, selv når enkelte poster afvises, så gennemgå altid hvert element og svaret på oversigtsniveau. Medtag svaret requestId, når Scoutello-support skal undersøge en fejl.

Tidsstempler og konflikter​

Når externalUpdatedAt er angivet, bruger Scoutello det til at afvise forældede ændringer uden at afvise resten af batchen. Et resultat af typen stale_ignored er endeligt for den ældre payload; hent den aktuelle post, før det afgøres, om der skal sendes en nyere version.

Betragt tidsstempler som UTC-værdier i ISO 8601-format. Bevar den oprindelige præcision, og erstat ikke tidspunktet for et synkroniseringsjob med kildens ændringstidspunkt.

Idempotens​

Idempotensgrænsen er integrationen plus externalId. Scoutello sammenligner en kanonisk payload-hash og den valgfri værdi externalUpdatedAt, så gentagne forsøg med den samme post ikke opretter dubletter og kan returnere unchanged.

Med externalUpdatedAt er det samme tidsstempel og den samme payload unchanged, et ældre tidsstempel er stale_ignored, og det samme tidsstempel med en anden payload er en versionskonflikt. For et link, der aldrig har accepteret et tidsstempel, forbliver den samme payload uden tidsstempel unchanged, mens en ændret payload anvendes i modtagelsesrækkefølge. Når et link har accepteret et tidsstempel, afvises en ændret payload, der udelader externalUpdatedAt, som en versionskonflikt, så data uden versionsoplysninger ikke kan overskrive en versioneret tilstand. Derfor anbefales kildens ændringstidsstempler kraftigt.

Revisionsspor​

Godkendte API-oprettelser, -opdateringer og synkroniseringshandlinger, der kun opretter links, vises i Scoutello-ændringslogge med Public API som kilde og knyttes til den ansvarlige integration. Operationelle kørselsoversigter gemmer anmodnings-ID'er og samlede resultatantal til fejlfinding; de gemmer ikke dataposter eller API-hemmeligheder.

Fejl og forsøg igen​

Fejl på anmodningsniveau bruger denne envelope:

{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}

Forsøg igen ved HTTP 429- og midlertidige 5xx-svar med eksponentiel backoff og jitter. Overhold Retry-After, når den er til stede. Netværksfejl kan være opstået, efter at Scoutello accepterede en anmodning; det er sikkert at sende samme batch igen, fordi hver post er idempotent ud fra eksternt ID og kanonisk payload. Forsøg ikke automatisk igen ved godkendelses-, autorisations-, validerings- eller versionskonfliktfejl eller ved individuelle rejected-resultater uden at ændre anmodningen.

Anbefalet tovejs-synkroniseringsloop​

  1. Kald /whoami under opsætningen, og kontrollér den forventede organisation og de forventede scopes.
  2. Læs hver side, der er ændret siden det senest fuldførte high-water mark, og anvend ændringerne idempotent i det eksterne system.
  3. Send eksterne ændringer til /batch-upsert ved hjælp af stabile eksterne ID'er og kildens ændringstidspunkter.
  4. Gem kun checkpoints, når alle sider og resultater for de enkelte poster er behandlet.
  5. Løs konflikter i henhold til kildesystemets ejerskabsregler; efterlign ikke sletninger ved at sende tomme poster.

Scoutello tilbyder med vilje ingen offentlig sletterute i denne første version. Håndter slette- eller arkiveringspolitikker uden for API'et, indtil der introduceres en dokumenteret livscyklusoperation.

Sociale opslag til manuel gennemgang​

Den sociale API klargør opslag til en navngiven menneskelig gennemser. Den kan ikke godkende eller udgive dem. REST og MCP bruger de samme scopes og den samme tjeneste.

ScopeEndpoints under /api/v1
social-channels.readGET /social-channels
social-posts.readGET /social-posts, GET /social-posts/{scoutelloId}
social-post-drafts.readGET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId}
social-post-drafts.writePOST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize

Nye scopes skal tildeles eksplicit. Eksisterende legitimationsoplysninger får ingen yderligere adgang. Brug members.read til at finde bruger-ID'er for medlemmer, og vælg en gennemser med tilladelse til at udgive opslag (newsletter.edit). Kladder kræver ikke en CRM-kontakt eller et projekt.

{
"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"]
}]
}
}]
}

Brug publishMode: "now" og scheduledAt: null til at publicere, når indholdet er godkendt. Hver kanalvariant indeholder sin komplette tekst, sine indstillinger og medie-id'er i den angivne rækkefølge. Kanalopdagelse returnerer understøttede formater, begrænsninger og indstillinger. De aktuelt understøttede kanaler er LinkedIn-profiler/-sider, Facebook, Instagram og Threads. Instagram kræver medier. En variant kan indeholde op til ti billeder eller videoer.

Batchanmodninger kan indeholde op til 100 unikke eksterne id'er inden for den eksisterende grænse på 1 MiB pr. anmodning. mode: "validate" kontrollerer referencer og versioner uden at gemme kladder, uploade aktiver, oprette notifikationer eller sætte arbejde i kø. Resultaterne af anvendelsen indeholder id'er, gennemgangslinks, versioner og resultater for hver post. Delvise fejl ruller ikke vellykkede relaterede poster tilbage. En fejl ved en notifikation returnerer en advarsel med den gemte URL til gennemgang.

Hent den aktuelle draftVersion, før en ventende kladde revideres. Identiske gentagelser er idempotente og bevarer efterfølgende manuelle redigeringer. Gennemgåere kan ikke ændres direkte. Efter godkendelse eller afvisning skal der bruges et nyt eksternt id til et nyt forslag. Læsning af kladder er begrænset til den kaldende integration. Opslagshistorikken omfatter alle gemte Scoutello-oprettede kampagner i organisationen, herunder opslag oprettet via dashboardet, scriptet og ældre Scoutello-opslag. Den importerer ikke ekstern kanalhistorik.

Lister bruger standardparametrene limit, cursor og updatedSince. Opslag og kladder accepterer også channelId, status, after, before og search. Bevar alle filtre på efterfølgende markørsider. Datofiltre gælder publiceringstidspunktet (oprettelsestidspunktet for ventende kladder, der skal publiceres med det samme). Kladdefilteret status filtrerer efter godkendelsesstatus; opslagsfilteret status matcher en kampagne- eller kanal-leveringsstatus. Læsninger viser den senest kendte leveringsstatus, fejl pr. kanal, offentlige links og tidspunkter for afstemning. Trinvise kladdelæsninger afspejler også ændringer i kampagneleveringen.

Upload medier​

  1. Kald POST /social-media/uploads med clientUploadId, filename, contentType, size i bytes og små hexadecimale bogstaver sha256 for de oprindelige bytes. Understøttede typer er PNG, JPEG, WebP, MP4, WebM, QuickTime og M4V. Uploadgrænsen er 500 MiB.
  2. Send de oprindelige bytes med HTTP PUT til den returnerede upload.url, og brug dens headers. Upload-URL'er udløber efter 15 minutter. Genbrug clientUploadId ved nye forsøg med den samme fil; udløbne sessioner eller andre filer kræver et nyt ID.
  3. Kald POST /social-media/uploads/{assetId}/finalize med en JSON-body på {}. Færdiggørelsen kontrollerer størrelse, type, signatur og checksum, låser en privat kopi og returnerer aktiv-ID'et til mediaIds. Gentagen færdiggørelse er sikker.

Ejerskab af uploads er knyttet til organisationen og integrationen. Kladder kan referere til færdiggjorte aktiver fra deres organisation. Preview-URL'er er midlertidige; hent kladden igen for at opdatere dem. Upload-URL'er udstedes aldrig til færdiggjorte objekter.

Menneskelig gennemgang og levering​

Anmelderen modtager en notifikation på dashboardet og kan åbne opslaget fra Opslag eller via dets anmeldelses-URL. Redigering opretter en ny uforanderlig version. Godkendelse bruger den viste version og indholdshashen, kontrollerer medlemskab, kanaler og aktiver igen og opretter atomisk én permanent kampagne. Hvis det foreslåede tidspunkt er overskredet, skal anmelderen gemme et nyt tidspunkt eksplicit eller vælge publicering ved godkendelse.

Køforsøg genbruger kampagnen og dens platformskvitteringer. Godkendte kampagner kan ikke redigeres direkte. Annullering via dashboardet bevarer deres godkendelseshistorik og medier; annullering kan ikke afbryde en aktiv afsendelse. Hent kladden eller kampagnen for at skelne mellem godkendelse og faktisk levering på platformen.