Scoutello API
Scoutello API är ett server-till-server-API för synkronisering i båda riktningarna av en organisations kontakter, uppgifter, protokoll, möjligheter, projekt, milstolpar och händelser. API:et tillhandahåller även skrivskyddad historik över utgående e-post, sökning efter tilldelningsbara medlemmar och upptäckt av entitetsanpassade taggar. Inkrementella GET/list-rutter och idempotenta batch-uppdateringar är synkroniseringsprimitiverna i den här versionen. API:et tillhandahåller inte borttagningsåtgärder eller webhooks.
API:ets bas-URL är:
https://admin.scoutello.com/api/v1
Den visas även i Organisationsinställningar → Utvecklare/API. OpenAPI-dokumentet finns på:
https://admin.scoutello.com/api/v1/openapi.json
Skapa och skydda en nyckel
För modulära organisationer måste CRM-modulen vara aktiv utöver nyckelns obligatoriska behörigheter. En giltig nyckel kan inte aktivera en modul som saknas. Förfrågningar returnerar HTTP 403 med felkoden module_not_active när CRM-åtkomst saknas. En person med organisationsadministrativa rättigheter kan granska eller aktivera CRM under Abonnemang; försöka igen när åtkomsten är aktiv.
En person med organisationsadministrativa rättigheter kan skapa en integration och API-nyckel i Organisationsinställningar → Utvecklare/API. Hela nyckeln visas en gång. Kopiera den till en lösenordshanterare innan dialogrutan stängs; Scoutello kan inte visa hela nyckeln igen.
- Använd en separat integration och nyckel för varje externt system och varje miljö.
- Ge endast de behörigheter som systemet behöver.
- Placera aldrig en nyckel i webbläsarkod, en URL, källkodshantering, loggar, supportmeddelanden eller klientlagring.
- Rotera nycklar enligt ett schema. När en aktiv integration roteras fungerar ersättningsnyckeln omedelbart och den tidigare nyckeln förblir giltig i högst 15 minuter, så att det externa systemet kan byta utan driftstopp. En tidigare angiven sluttid gäller fortfarande, så den tidigare nyckeln kan sluta fungera tidigare.
- Om en nyckel kan ha blivit exponerad: pausa integrationen innan nyckeln roteras. När integrationen pausas avvisas alla dess nycklar tillfälligt. En rotation medan integrationen är pausad har ingen överlappning: den tidigare nyckeln förblir inaktiverad och ersättningsnyckeln förblir inaktiverad tills integrationen återupptas.
- Återkalla hela integrationen permanent när ett externt system kopplas från. Återkallandet inaktiverar alla dess nycklar och kan inte ångras.
Skicka nyckeln med varje autentiserad förfrågan:
Authorization: Bearer YOUR_API_KEY
Bearer-autentisering rekommenderas. Klienter som inte kan ange Authorization kan använda x-api-key i stället. Skicka inte båda rubrikerna; förfrågningar med olika värden i de båda rubrikerna avvisas.
API:et är avsett för backend-klienter och aktiverar inte åtkomst från webbläsare över olika ursprung.
Använd GET /whoami efter att en nyckel har konfigurerats för att verifiera integrationen, organisationen, behörigheterna och nyckelbegränsningarna utan att hämta personuppgifter.
Behörigheter
| Omfattning | Tillåter |
|---|---|
contacts.read | Lista och hämta kontakter. Kontakter för organisationskonton och medlemmar med åtkomst är undantagna. |
contacts.write | Validera och tillämpa kontaktupserts. |
tasks.read | Lista och hämta icke-privata uppgifter. |
tasks.write | Validera och tillämpa uppgiftsupserts. |
protocols.read | Lista och hämta icke-privata protokoll. |
protocols.write | Validera och tillämpa protokollupserts. |
opportunities.read | Lista och hämta möjligheter. |
opportunities.write | Validera och tillämpa möjlighetssupserts. |
projects.read | Lista och hämta projekt. |
projects.write | Validera och tillämpa projekt- och deltagarupserts. |
milestones.read | Lista och hämta projektmilstolpar. |
milestones.write | Validera och tillämpa milstolpsupserts. |
members.read | Lista accepterade medlemmar med endast medlemskund-ID, användar-ID och visningsnamn. |
events.read | Lista och hämta händelser och centrala scheman. |
events.write | Validera och tillämpa händelseupserts. |
mails.read | Läsa historik över skickad och misslyckad utgående e-post som ägs av organisationen. |
mail-drafts.read | Läsa den här integrationens fristående utkast för e-postgodkännande och leveransstatus. |
mail-drafts.write | Förbereda eller ändra e-postutkast för mänskligt godkännande; aldrig godkänna eller skicka. |
tags.read | Hitta valbara taggar för entitetstyper som stöds. |
Privata uppgifter och protokoll returneras aldrig av detta API. Om en omfattning saknas returneras ett auktoriseringsfel; det behandlas inte som ett tomt resultat.
En CRM-kontakt som inte är medlem kan läsas och refereras även när den är kopplad till en Scoutello-inloggning. Svaret innehåller endast organisationens CRM-fält, aldrig användaridentitet eller åtkomstfält. Kontakter med en roll, behörigheter, inbjudan, godkännande eller organisationskontostatus förblir dolda. Det är fortfarande inte tillåtet att redigera en kontakt som är kopplad till en inloggning (protected_contact), inklusive CRM-fält som annars är oförändrade. För att referera till en befintlig läsbar kontakt från en uppgift eller ett protokoll kan contacts.write upprätta dess externa länk med endast externalId, scoutelloId och valfritt externalUpdatedAt. Senare uppdateringar som endast gäller länkmetadata använder externalId och valfritt externalUpdatedAt; utelämna bootstrap-identifieraren scoutelloId när länken väl har upprättats. Detta ändrar aldrig kontakten eller dess användare. Tilldelning av accepterade medlemmar använder den separata projektionen members.read.
Nya nycklar använder prefixet sctl_api_ och börjar endast med contacts.write. Alla andra scopes kräver ett uttryckligt godkännande som en organisationsadministratör måste bevilja när en nyckel skapas eller roteras. Befintliga autentiseringsuppgifter behåller sina aktuella scopes och förblir giltiga.
Projektkopplade kontakter och e-postutkast
Kontaktupserts accepterar valfria par av projectScoutelloId / projectExternalId och companyScoutelloId / companyExternalId (välj ett per par). Kontakten, företagsrelationen och projektmedlemskapet sparas atomiskt per objekt. Att lägga till ett projektmedlemskap kräver projects.write; utelämnade referenser bevarar andra relationer och medlemskap. Vid läsning av kontaktdetaljer inkluderas projectParticipations när projects.read har beviljats. Agenter för säljprojekt måste uttryckligen inkludera projektreferensen, även när en befintlig kontakt återanvänds.
Fristående utkast använder det befintliga systemet för mänskligt godkännande, utan en workflowkörning:
| Metod | Sökväg | Syfte |
|---|---|---|
| GET | /mail-drafts | Integrationsägda utkast med sidindelning; valfria filter för projectScoutelloId och status. |
| GET | /mail-drafts/{scoutelloId} | Aktuell version, granskningslänk, innehållshash, status för godkännande/skickande och slutligt e-post-ID. |
| GET | /mail-drafts/external/{externalId} | Slå upp ett stabilt externt integrations-ID. |
| POST | /mail-drafts/batch-upsert | Validera eller tillämpa utkastets förberedelse. |
Förberedelse av utkast kräver mail-drafts.write, contacts.read och projects.write. Den refererade kontakten blir projektdeltagare. Den som godkänner måste vara en accepterad organisationsmedlem med behörighet att redigera e-post. Val av avsändare använder den medlemmenes befintliga tillåtna organisations- eller personliga avsändarinställningar; godtyckliga From-adresser accepteras inte.
{
"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."
}
}]
}
Kontrollera varje valideringsresultat innan en ny begäran görs med mode: "apply". Läs det resulterande ID:t för att hämta reviewUrl, draftVersion, contentHash, status, dispatchStatus och mailScoutelloId. Använd expectedVersion: 0 endast vid skapande och den aktuella returnerade versionen vid revideringar. Kontext och godkännare är oföränderliga; granskade eller distribuerade utkast avvisar ändrat innehåll. Identiska försök returnerar det ursprungliga utkastet.
Utkast visas på flikarna E-post för projekt och kontakter samt i aviseringar om godkännande på dashboarden. Förberedelse via API skickar inga e-postmeddelanden, inklusive aviseringsmeddelanden; befintligt beteende för e-postaviseringar i arbetsflöden är oförändrat. Den tilldelade personen kan redigera mottagare, ämne, brödtext och bilagor som stöds, spara versionen och sedan välja Godkänn och skicka. Integrationer kan inte godkänna eller skicka meddelanden. Misslyckad eller tvetydig leverans görs aldrig om automatiskt utan kontroll. Vid konvertering av protokollbaserade utkast ska protokollen bevaras och ersättningarna korsrefereras.
MCP-åtkomst
Samma Scoutello API-nyckel och behörighetsomfattningar kan användas med MCP-slutpunkten för streamable HTTP:
https://admin.scoutello.com/api/v1/mcp
Konfigurera MCP-klienten så att den skickar Authorization: Bearer YOUR_API_KEY. Den äldre /api/mcp-URL:en finns kvar som ett sökvägskompatibilitetsalias, men nya klienter bör använda den versionshanterade slutpunkten. Tidigare sctl_mcp_-autentiseringsuppgifter accepteras inte; ersätt dem med en Scoutello-integrationsnyckel för API:et.
MCP-verktygen motsvarar REST-kontraktet direkt och använder samma körningsscheman, klientkontroller, integrationslivscykel, hastighetsbegränsning och tjänstmetoder. Exempelvis motsvarar contacts_list, contacts_get, contacts_get_by_external_id och contacts_batch_upsert de fyra kontaktvägarna. Samma mönster gäller för uppgifter, protokoll, möjligheter, projekt, milstolpar och händelser; e-post tillhandahåller mails_list och mails_get, medlemmar tillhandahåller members_list och taggar tillhandahåller tags_list.
Servern visar endast verktyg som tillåts av den aktuella nyckelns behörighetsomfattningar. En nyckel med contacts.read kan hitta verktygen för att läsa kontakter, men inte contacts_batch_upsert; en nyckel med contacts.write får verktyget för batchuppdatering, men inte läsverktygen. whoami är alltid tillgängligt. Skrivverktyg har samma omedelbara effekter som motsvarande REST-anrop. Använd därför mode: "validate" när ett anrop ska granska en batch utan att tillämpa den.
MCP används också server-till-server och aktiverar inte åtkomst från webbläsare över olika ursprung. Dess JSON-RPC-transport kräver en särskild URL och kan därför inte dela en enskild REST-resurs-URL, även om autentisering och databeteende är gemensamma.
Fullständiga instruktioner för klientkonfiguration, verifiering, verktygsmappning och felsökning finns i integrationsguiden för MCP.
Läsa poster
Kontakter, uppgifter, protokoll, möjligheter, projekt, milstolpar och händelser använder samma läsvägar:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
Ersätt contacts med tasks, protocols, opportunities, projects, milestones eller events för de andra synkroniseringsresurserna. externalId visas i ett läs-DTO när posten har länkats av den här integrationen.
Ett listsvar har detta omslag:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit måste vara mellan 1 och 100. Resultaten sorteras efter den effektiva tidpunkt då deras offentliga API-representation ändrades och därefter efter Scoutello-ID. Den effektiva tidpunkten kan vara senare än den returnerade entiteten updatedAt när metadata för integrationslänken ändrades. Cursorvärden är opaka: lagra och skicka dem oförändrade och försök inte utläsa någon betydelse ur innehållet.
Det första svaret fastställer snapshotAt för den genomläsningen. Följ nextCursor tills hasMore är false innan en annan inkrementell läsning påbörjas. Detta förhindrar att poster som ändras under pagineringen gör den aktuella genomläsningen instabil.
För inkrementell synkronisering ska alla cursor-sidor bearbetas och därefter ska genomläsningens snapshotAt sparas som den högsta tidsstämpeln. Skicka den som ISO 8601-värdet updatedSince vid nästa genomläsning. Den nedre gränsen är inkluderande, så en ny körning av en slutförd ögonblicksbild kan returnera poster på gränsen men kan inte hoppa över dem.
Ett svar för en enskild post har detta omslag:
{
"data": {},
"requestId": "request-id"
}
Svar för enskilda kontakter innehåller även en array med relations. Varje relation behåller sitt Scoutello-relations-ID, skapandetid, typ, anteckningar samt connectedFrom- och connectedTo-kontaktreferenser. Kontaktreferenser innehåller Scoutello-ID:t och den här integrationens externa ID när ett sådant finns. Kontakter som utesluts av API:ts sekretessgräns för organisationsåtkomst exponeras inte genom relationer.
Listsvaret för kontakter är kompakt och innehåller inte relationer. Använd någon av rutterna för enskilda kontakter när relationsinformation behövs.
Arbetsfilter och cursorns omfång
Kontaktlistor accepterar search, type (person, company, supplier, other), status och tagIds. Sökningen trimmas, är skiftlägesokänslig och begränsas till 200 tecken / 10 blankstegsseparerade token. Varje token måste förekomma i minst ett av firstName, lastName eller companyName, inklusive äldre företagsnamn som lagras i lastName. Tecken som % och _ matchas bokstavligt. Taggar använder matchning av typen någon av med 1–50 ID:n. Alla angivna filter kombineras med AND. REST kodar tagg-ID:n som upprepade parametrar; MCP tillhandahåller en array:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
Kontaktcursors är bundna till organisationen, integrationen och varje filter. Behåll filtren på varje sida; om ett filter ändras avvisas cursorn. Taggordning/dupliceringar och ordning, skiftläge och blanksteg mellan söktoken ändrar inte det effektiva filtret.
Arbetslistevägar accepterar följande ytterligare filter; andra kombinationer av resurs och fält avvisas:
| Resurs | Filter |
|---|---|
| Uppgifter | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Protokoll | projectScoutelloId, milestoneScoutelloId, status (draft eller final) |
| Möjligheter | projectScoutelloId, stage, ownerScoutelloUserId |
| Projekt | status, assignedContactScoutelloId |
| Milstolpar | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
dueBefore är exklusivt; dueAfter är inklusivt. De jämför uppgiftens förfallodatum eller milstolpens slutdatum; poster utan sådant datum matchar inte. Ange ISO-datum och -tid med tidszon. Alla filter tillämpas före paginering. Fortsätt en markör med exakt samma filter, inklusive updatedSince, och samma organisation/integration. Sidstorleken får ändras. Äldre markörer utan avgränsning måste efter denna version startas om från den sparade högvattenstämpeln.
Projekt, milstolpar, tilldelningar och anteckningar
GET /members (MCP members_list) använder standardpaginering och kräver members.read. Den returnerar scoutelloId (medlems-Customer-ID), scoutelloUserId (User-ID) och displayName. Endast godkända organisationsmedlemmar med en roll visas; uppslagningen visar inte e-postadresser eller behörigheter.
Uppgifter accepterar assignedScoutelloUserIds; möjligheter använder ownerScoutelloUserId. Projekt och milstolpar använder assignedContacts: [{"scoutelloId":"member-customer-id"}]. Tilldelningar kräver godkända medlemmar i autentiseringsuppgifternas organisation. Utelämnade tilldelningar förblir oförändrade; [] rensar dem. Importer av projekt, milstolpar, uppgifter och protokoll är tysta: de skickar inga tilldelningsaviseringar eller annan kommunikation.
Händelsen assignedContacts stöder läsbara CRM-kontakter och godkända medlemmar som anges med medlems-Customer-ID. Godkända medlemmar är fortsatt otillgängliga som vanliga CRM-kontaktreferenser eller mål för externa länkar; använd medlemsfältet för tilldelning för teamansvar.
Skapa milstolpar med ett name och antingen projectScoutelloId eller projectExternalId. De har stöd för description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (standardvärdet är 0) och assignedContacts. Slutdatum får inte infalla före startdatumet. Varje milstolpe har en stabil extern länk som är avgränsad till integrationen. Projektet kan inte ändras via API:t. När milstolpar skapas och uppdateras lokaliseras namn och beskrivning till organisationens språk.
Uppgifter och protokoll accepterar referenser till projekt, milstolpar och möjligheter som <entity>ScoutelloId eller <entity>ExternalId, till exempel milestoneExternalId. Ange endast en stavning per relation, även vid rensning med null. Alla relationer måste tillhöra autentiseringsuppgiftens organisation. En referens som endast anger en milstolpe härleder projektet. Ett motstridigt projekt, eller att uttryckligen rensa ett projekt samtidigt som dess milstolpe behålls, avvisas. En länkad möjlighet med ett projekt måste överensstämma med arbetsobjektets projekt. Utelämnade relationer behåller sina aktuella värden. Ett uttryckligt null rensar en relation när den återstående kontexten är giltig. Läsningar visar båda ID-stavningarna och tilldelningar av uppgifter.
Uppgiftsplanering och arbetsflöden
status för uppgifter är den oföränderliga nyckeln för en status i uppgiftens effektiva arbetsflöde, inte en fast enum. Läs tillgängliga organisations- och projektarbetsflöden med GET /task-workflows genom att använda omfånget tasks.read. Varje status innehåller sin nyckel, etikett, livscykel-type (backlog, unstarted, started, completed eller cancelled), färg, ordning, standardflagga och arkiveringsstatus. Projektposter anger om organisationsarbetsflödet ärvs. Konfigurationen av arbetsflöden administreras fortfarande via instrumentpanelen.
Uppgifter accepterar nullable priority (low, medium, high eller urgent) och estimatedEffortMinutes, samt nullable startDate och dueDate. Vid läsning av uppgifter inkluderas det denormaliserade statusType, referens till överordnad uppgift, kompakta referenser till deluppgifter samt referenser till blockedBy / blocks.
Skapa eller uppdatera en underuppgift på en nivå med antingen parentTaskScoutelloId eller parentTaskExternalId; null flyttar den till en uppgift på toppnivå. Beroenden använder arrayer med referenser till { "scoutelloId": "..." } eller { "externalId": "..." } i blockedBy och blocks. Utelämnade relationsfält bevarar dem, medan en tom beroendearray rensar den riktningen. API:et avvisar kapslade underuppgifter, beroenden mellan överordnade och underordnade uppgifter, beroenden mellan organisationer, dubbletter, självreferenser samt direkta eller transitiva cykler.
Filter för uppgiftslistor accepterar ett exakt arbetsflöde status, en livscykel statusType, priority, parentState (top_level, subtask eller parent) samt blockedState (blocked, blocking eller unblocked).
Protokoll accepterar dessutom status: "draft" | "final" (nya poster får som standard final). Ett nytt protokoll kräver type, date samt antingen en kontakt eller giltig projekt-/milstolpekontext. contactExternalId: null rensar kontakten endast när projekt-/milstolpekontexten finns kvar. Interna projektnoteringar kan därför skapas och läsas utan att en kund behöver anges. Draft/final beskriver noteringens status och skickar aldrig någon kommunikation. Privata uppgifter och protokoll förblir otillgängliga.
Projektmedverkande
Projektets participants innehåller kompletterande upserts, identifierade med en referens till contact, till exempel:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
Medverkande beskriver prospekt/kunder som är kopplade till ett projekt; ansvariga medlemmar anges genom tilldelningar. Utelämnade medverkande, en tom array och utelämnade medverkandefält bevarar befintliga data. null rensar role, notes eller groupScoutelloId. Dubbletter av matchade kontakter i samma nyttolast avvisas. Grupper måste redan tillhöra det valda projektet; läsningar inkluderar participantGroups (ID/namn) samt medverkande-ID:n, kontakter, roll, anteckningar och grupp-ID. Det går för närvarande att ta bort medverkande eller skapa grupper i kontrollpanelen.
Batch-upsert av poster
Skriv upp till 100 poster med resursens batchrutt:
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"
}
]
}
Batchar med uppgifter matchar sina uppgiftsposter innan relationer till överordnade uppgifter och beroenden tillämpas. Denna tvåfasbearbetning gör det möjligt för en överordnad uppgift, blockerare eller blockerad uppgift att hänvisa till en annan uppgift som skapas i samma batch med dess externa ID, oavsett posternas ordning.
Använd OpenAPI-dokumentet för varje resurs fält och valideringsbegränsningar. Varje post måste ha en stabil externalId på mellan 1 och 200 tecken. Behandla den som en ogenomskinlig teknisk identifierare: använd inte en e-postadress, ett namn, en API-hemlighet eller andra personuppgifter. externalUpdatedAt är valfritt, men rekommenderas starkt när källsystemet tillhandahåller en tillförlitlig ändringstidpunkt.
Begärans brödtext är begränsad till 1 MiB. mode har standardvärdet apply:
applyvaliderar och skriver godkända poster.validateutför samma validering och matchning utan att skriva, och returnerar resultat enligtwould_*.
För kontaktimporter kan matchByEmail ställas in på true i begäran. Standardvärdet är false; externt ID är den säkrare identitetsgränsen.
Utelämnade fält behåller det aktuella värdet. Ett uttryckligt null rensar ett nullbart fält, och en angiven tom tilldelnings- eller taggarray rensar den relationen. Projekt- participants är additiva upserts: en tom array lämnar deltagarlistan oförändrad. Skrivningar av taggar för kontakter, uppgifter, möjligheter och händelser använder Scoutello-tagg-ID:n. Relationers externa ID:n matchas endast via länkar som tillhör den aktuella integrationen, medan Scoutello-användar-ID:n som används för ägarskap eller ansvar måste identifiera godkända medlemmar i den aktuella organisationen.
När möjligheter skapas krävs ett konto eller en kontakt, och för förlorade möjligheter krävs en förlustorsak. Penningbelopp anges i hela cent som heltal. Projekt- och händelsenamn samt beskrivningar läses och skrivs på organisationens konfigurerade språk. Skrivningar av händelser stöder uttryckliga datum samt daglig, veckovis eller månadsvis återkommande schemaläggning med undantag; publicerade synlighetsnivåer omfattas fortfarande av Scoutellos krav för juridisk beredskap. API:t exponerar inte biljettförsäljning för händelser, deltagare, medier, mallar, nyhetsbrev, samarbeten eller andra avancerade funktioner för händelsehantering.
Upptäcka taggar
Använd taggendpointen innan tagIds anges:
GET /tags?entity=events&type=category
entity krävs och accepterar contacts, tasks, opportunities eller events. Den mappas till motsvarande lagrade taggrelevans. type är valfritt och accepterar category eller attribute. Valbara kategorier kan ägas av organisationen eller vara globala; valbara attribut kommer från Scoutellos kurerade globala attributuppsättning. Resultaten innehåller scoutelloId, namnet lokaliserat till organisationens språk, type och relevancy. Tagg-ID:n från andra organisationer, tagg-ID:n med fel relevans och tagg-ID:n som inte är valbara avvisar det berörda batchobjektet.
Läsa historik över utgående e-post
E-posthistoriken är skrivskyddad:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Endast organisationsägd e-post med statusen sent eller failed returneras. Svaren innehåller vanliga lagrade headers och meddelandetext, BCC, status och tidsstämplar, referenser till projekt/event/nyhetsbrev, bilage-ID:n och bilagetyper samt aggregerad statistik över leveranser, öppningar, klick, studsar, klagomål och avvisningar för mottagare. Utkast, köad eller schemalagd e-post, rader per mottagare, renderade ögonblicksbilder, råa leverantörsfel och URL:er för nedladdning av bilagor exponeras aldrig. En senare uppdatering av mottagarleveransen flyttar e-postens effektiva synkroniseringstidpunkt framåt, så att e-posten åter visas i inkrementella läsningar. Det finns inga rutter för att skriva e-post.
Ett appliceringsresultat kan vara created, updated, linked, unchanged, stale_ignored eller rejected. Validering använder would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale eller rejected. En giltig batchbegäran returnerar HTTP 200 även när enskilda poster avvisas, så kontrollera alltid varje post och sammanfattningen i svaret. Inkludera svaret requestId när Scoutello-supporten ska undersöka ett fel.
Tidsstämplar och konflikter
När externalUpdatedAt finns använder Scoutello det för att avvisa inaktuella ändringar utan att resten av batchen misslyckas. Resultatet stale_ignored är slutgiltigt för den äldre nyttolasten; hämta den aktuella posten innan en nyare version skickas.
Behandla tidsstämplar som UTC-värden i ISO 8601-format. Behåll den ursprungliga precisionen och ersätt inte källpostens ändringstid med tiden då ett synkroniseringsjobb kördes.
Idempotens
Idempotensgränsen utgörs av integrationen och externalId. Scoutello jämför en kanonisk hash av nyttolasten och det valfria värdet externalUpdatedAt, så att ett nytt försök med samma post inte skapar dubbletter och kan returnera unchanged.
Med externalUpdatedAt är samma tidsstämpel och nyttolast unchanged, en äldre tidsstämpel stale_ignored och samma tidsstämpel med en annan nyttolast en versionskonflikt. För en länk som aldrig har godkänt en tidsstämpel förblir samma nyttolast utan tidsstämpel unchanged, medan en ändrad nyttolast tillämpas i ankomstordning. När en länk har godkänt en tidsstämpel avvisas en ändrad nyttolast som utelämnar externalUpdatedAt som en versionskonflikt, så att versionslös data inte kan skriva över versionshanterat tillstånd. Därför rekommenderas källans ändringstidsstämplar starkt.
Granskningslogg
Godkända API-skapanden, uppdateringar och synkroniseringsåtgärder som endast länkar poster visas i Scoutellos ändringsloggar med Public API som källa och kopplas till den ansvariga integrationen. Operativa körningssammanfattningar sparar begärande-ID:n och sammanräknade resultat, vilket underlättar felsökning. De sparar inte postinnehåll eller API-hemligheter.
Fel och återförsök
Fel på begärandenivå använder detta omslag:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
Försök igen vid HTTP 429 och tillfälliga 5xx-svar, med exponentiell backoff och jitter. Följ Retry-After när den finns. Nätverksfel kan ha inträffat efter att Scoutello godkänt en begäran. Det är säkert att skicka samma batch igen eftersom varje post är idempotent utifrån externt ID och kanoniskt innehåll. Försök inte automatiskt igen med autentiserings-, behörighets-, validerings- eller versionskonfliktsfel eller individuella rejected-resultat utan att ändra begäran.
Rekommenderad tvåvägsloop för synkronisering
- Anropa
/whoamiunder konfigurationen och verifiera förväntad organisation och behörighetsomfattningar. - Läs varje sida som har ändrats sedan den senaste slutförda högvattenmarkeringen och tillämpa ändringarna idempotent i det externa systemet.
- Skicka externa ändringar till
/batch-upsertmed stabila externa ID:n och tidsstämplar för källsystemets ändringar. - Spara kontrollpunkter först när alla sidor och postresultat har hanterats.
- Lös konflikter enligt källsystemets ägarskapsregler. Efterlikna inte raderingar genom att skicka tomma poster.
Scoutello tillhandahåller medvetet ingen offentlig raderingsväg i denna första version. Hantera raderings- eller arkiveringspolicyer utanför API:t tills en dokumenterad livscykelåtgärd införs.
Sociala inlägg för mänsklig granskning
Det sociala API:t förbereder inlägg för en namngiven person som ska granska dem. Det kan inte godkänna eller publicera dem. REST och MCP använder samma behörighetsomfattningar och tjänst.
| Omfattning | Slutpunkter 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 |
Nya behörighetsomfattningar måste uttryckligen beviljas. Befintliga autentiseringsuppgifter får ingen ytterligare åtkomst. Använd members.read för att hitta användar-ID:n för medlemmar och välj en granskare med behörighet att publicera (newsletter.edit). Utkast kräver ingen CRM-kontakt eller något 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"]
}]
}
}]
}
Använd publishMode: "now" och scheduledAt: null för publicering när innehållet har godkänts. Varje
kanalvariant innehåller sin fullständiga text, sina inställningar och ordnade medie-ID:n.
Kanalidentifiering returnerar format, begränsningar och inställningar som stöds. De kanaler som
för närvarande stöds är LinkedIn-profiler/-sidor, Facebook, Instagram och Threads.
Instagram kräver media. En variant kan innehålla upp till tio bilder eller videor.
Batchar kan innehålla upp till 100 unika externa ID:n inom den befintliga gränsen på 1 MiB per begäran.
mode: "validate" kontrollerar referenser och versioner utan att spara utkast,
ladda upp resurser, skapa aviseringar eller lägga arbete i kö. Resultat från tillämpningen innehåller
ID:n, granskningslänkar, versioner och utfall per post. Partiella fel återställer inte
lyckade poster i samma batch. Ett aviseringsfel returnerar en varning med den sparade
gransknings-URL:en.
Hämta det aktuella draftVersion innan ett väntande utkast revideras. Identiska
försök är idempotenta och bevarar senare manuella ändringar. Granskare kan inte ändras
direkt. Efter godkännande eller avslag används ett nytt externt ID för ett annat förslag.
Utläsning av utkast är begränsad till den anropande integrationen. Publiceringshistoriken omfattar all
beständig Scoutello-skapad kampanjdata i organisationen, inklusive inlägg från kontrollpanelen,
skript och äldre Scoutello-inlägg. Extern kanalhistorik importeras inte.
Listor använder standardparametrarna limit, cursor och updatedSince. Inlägg och
utkast accepterar även channelId, status, after, before och search. Behåll
alla filter på efterföljande markörsidor. Datumfilter tillämpas på publiceringstid
(skapandetid för omedelbara väntande utkast). status för utkast filtrerar godkännande-
status. status för inlägg matchar en kampanj eller kanalens leveransstatus. Utläsningar visar
det senast kända leveranstillståndet, kanalvisa fel, offentliga länkar och tidsstämplar för
avstämning. Inkrementella utläsningar av utkast återspeglar även ändringar i kampanjens leveransstatus.
Ladda upp media
- Anropa
POST /social-media/uploadsmedclientUploadId,filename,contentType,sizei byteformat och det ursprungliga byteinnehålletssha256i gemener. Följande typer stöds: PNG, JPEG, WebP, MP4, WebM, QuickTime och M4V. Uppladdningsgränsen är 500 MiB. - Skicka originalbyteinnehållet med HTTP
PUTtill den returneradeupload.urloch använd dess headers. Uppladdningsadresser upphör att gälla efter 15 minuter. ÅteranvändclientUploadIdvid nya försök för samma fil; utgångna sessioner eller andra filer kräver ett nytt ID. - Anropa
POST /social-media/uploads/{assetId}/finalizemed en JSON-body på{}. Slutförandet kontrollerar storlek, typ, signatur och kontrollsumma, låser en privat kopia och returnerar tillgångs-ID:t förmediaIds. Upprepat slutförande är säkert.
Uppladdningsägarskapet är knutet till organisationen och integrationen. Utkast kan hänvisa till slutförda tillgångar från den egna organisationen. Förhandsgranskningsadresser är tillfälliga; hämta utkastet igen för att uppdatera dem. Uppladdningsadresser utfärdas aldrig för slutförda objekt.
Manuell granskning och leverans
Granskaren får en avisering i dashboarden och kan öppna inlägget från Postings eller via dess granskningsadress. Redigering skapar en annan oföränderlig version. Godkännande använder den visade versionen och innehållshashvärdet, kontrollerar medlemskap, kanaler och tillgångar på nytt och skapar atomiskt en beständig kampanj. Om den föreslagna tiden har passerat måste granskaren spara en uttryckligen ny tid eller välja publicering vid godkännande.
Försök i kön återanvänder kampanjen och dess plattformskvitton. Godkända kampanjer kan inte redigeras på plats. Avbrytning via dashboarden bevarar godkännandehistoriken och medierna; avbrytning kan inte avbryta en aktiv utsändning. Kontrollera utkastet eller kampanjen för att skilja godkännande från faktisk leverans på plattformen.