Naar hoofdinhoud gaan

Scoutello API

De Scoutello API is een server-naar-server-API voor het in beide richtingen synchroniseren van contacten, taken, protocollen, kansen, projecten, mijlpalen en gebeurtenissen van een organisatie. Daarnaast biedt de API alleen-lezen toegang tot de geschiedenis van uitgaande e-mails, het opzoeken van toewijsbare leden en het ontdekken van entiteitsgerichte tags. Incrementele GET/list-routes en idempotente batch-updates zijn in deze versie de basiselementen voor synchronisatie. Verwijderbewerkingen en webhooks worden niet ondersteund.

De basis-URL van de API is:

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

Deze URL staat ook in Organisatie-instellingen → Developer/API. Het OpenAPI-document is beschikbaar op:

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

Een sleutel aanmaken en beveiligen​

Voor modulaire organisaties moet naast de vereiste scopes van de sleutel ook de CRM-module actief zijn. Met een geldige sleutel kan een ontbrekende module niet worden geactiveerd. Verzoeken leveren HTTP 403 met foutcode module_not_active op wanneer CRM-toegang niet beschikbaar is. CRM controleren of activeren via Abonnement; na het activeren van de toegang opnieuw proberen.

Een organisatiebeheerder kan een integratie en API-sleutel aanmaken via Organisatie-instellingen → Developer/API. De volledige sleutel wordt één keer weergegeven. De sleutel vóór het sluiten van het dialoogvenster kopiëren naar een geheimenbeheerder; Scoutello kan de volledige sleutel daarna niet opnieuw tonen.

  • Voor elk extern systeem en elke omgeving een afzonderlijke integratie en sleutel gebruiken.
  • Alleen de scopes toekennen die het systeem nodig heeft.
  • Een sleutel nooit opnemen in browsercode, een URL, broncodebeheer, logboeken, supportberichten of client-side opslag.
  • Sleutels volgens een vast schema rouleren. Bij het rouleren van een actieve integratie werkt de vervangende sleutel onmiddellijk en blijft de vorige sleutel maximaal 15 minuten geldig, zodat het externe systeem zonder onderbreking kan overschakelen. Een eerder ingestelde vervaldatum blijft van toepassing; daardoor kan de vorige sleutel eerder stoppen met werken.
  • Bij een mogelijke blootstelling van een sleutel de integratie pauzeren voordat de sleutel wordt gerouleerd. Tijdens het pauzeren worden alle sleutels van de integratie tijdelijk geweigerd. Rouleren terwijl de integratie is gepauzeerd kent geen overlap: de vorige sleutel blijft uitgeschakeld en de vervangende sleutel blijft uitgeschakeld totdat de integratie wordt hervat.
  • Bij het verbreken van de verbinding met een extern systeem de volledige integratie permanent intrekken. Door intrekking worden alle sleutels ervan uitgeschakeld; dit kan niet ongedaan worden gemaakt.

De sleutel bij elk geauthenticeerd verzoek meesturen:

Authorization: Bearer YOUR_API_KEY

Bearer-authenticatie heeft de voorkeur. Clients die Authorization niet kunnen instellen, kunnen in plaats daarvan x-api-key gebruiken. Beide headers niet meesturen; verzoeken met verschillende waarden in beide headers worden afgewezen.

De API is bedoeld voor backend-clients en staat geen browsertoegang vanaf andere origins toe.

GET /whoami gebruiken nadat een sleutel is geconfigureerd om de integratie, organisatie, scopes en sleutellimieten te controleren zonder persoonlijke gegevens van personen op te vragen.

Scopes​

ScopeStaat toe
contacts.readContacten weergeven en ophalen. Contacten van organisatieaccounts en leden met toegang worden uitgesloten.
contacts.writeContact-upserts valideren en toepassen.
tasks.readNiet-privétaken weergeven en ophalen.
tasks.writeTaak-upserts valideren en toepassen.
protocols.readNiet-privéprotocollen weergeven en ophalen.
protocols.writeProtocol-upserts valideren en toepassen.
opportunities.readOpportunities weergeven en ophalen.
opportunities.writeOpportunity-upserts valideren en toepassen.
projects.readProjecten weergeven en ophalen.
projects.writeProject- en deelnemer-upserts valideren en toepassen.
milestones.readProjectmijlpalen weergeven en ophalen.
milestones.writeMijlpaal-upserts valideren en toepassen.
members.readGeaccepteerde leden weergeven met alleen het Customer ID, User ID en de weergavenaam van het lid.
events.readGebeurtenissen en kernplanningen weergeven en ophalen.
events.writeGebeurtenis-upserts valideren en toepassen.
mails.readGeschiedenis van verzonden en mislukte uitgaande e-mails van de organisatie lezen.
mail-drafts.readZelfstandige concepten voor e-mailgoedkeuring en de bezorgstatus van deze integratie lezen.
mail-drafts.writeE-mailconcepten voorbereiden of aanpassen voor menselijke goedkeuring; nooit goedkeuren of verzenden.
tags.readSelecteerbare tags voor ondersteunde entiteitstypen ontdekken.

Privétaken en -protocollen worden nooit door deze API geretourneerd. Bij een ontbrekende scope wordt een autorisatiefout geretourneerd; dit wordt niet behandeld als een leeg resultaat.

Een niet-lid als CRM-contact kan worden gelezen en als verwijzing worden gebruikt, ook wanneer het contact aan een Scoutello-login is gekoppeld. De respons bevat uitsluitend de CRM-velden van de organisatie, nooit User-identiteits- of toegangsvelden. Contacten met een rol, machtigingen, uitnodiging, acceptatie of organisatieaccountstatus blijven verborgen. Het bewerken van een aan een login gekoppeld contact blijft verboden (protected_contact), ook wanneer verder geen CRM-velden worden gewijzigd. Als een bestaand, leesbaar contact vanuit een taak/protocol moet worden verwezen, kan contacts.write de externe koppeling ervan tot stand brengen met alleen externalId, scoutelloId en optioneel externalUpdatedAt. Latere updates die alleen de koppelingsmetadata wijzigen, gebruiken externalId en optioneel externalUpdatedAt; laat de bootstrapwaarde scoutelloId weg zodra de koppeling tot stand is gebracht. Dit wijzigt nooit het contact of diens User. De toewijzing van geaccepteerde leden gebruikt de afzonderlijke members.read-projectie.

Nieuwe sleutels gebruiken het voorvoegsel sctl_api_ en starten uitsluitend met contacts.write. Voor elke andere scope is expliciete opt-in vereist, die een organisatiebeheerder moet toekennen bij het aanmaken of roteren van een sleutel. Bestaande credentials behouden hun huidige scopes en blijven geldig.

Projectgekoppelde contacten en e-mailconcepten​

Contact-upserts accepteren optionele paren projectScoutelloId / projectExternalId en companyScoutelloId / companyExternalId (kies één paar per type). Het contact, de bedrijfsrelatie en het projectlidmaatschap worden per item atomair opgeslagen. Voor het toevoegen van projectlidmaatschap is projects.write vereist; weggelaten verwijzingen behouden andere relaties en lidmaatschappen. Bij het opnieuw ophalen van contactgegevens wordt projectParticipations opgenomen wanneer projects.read is toegekend. Agents voor salesprojecten moeten de projectverwijzing expliciet opnemen, ook bij hergebruik van een contact.

Zelfstandige concepten gebruiken het bestaande systeem voor menselijke goedkeuring, zonder workflow-uitvoering:

MethodePadDoel
GET/mail-draftsGepagineerde concepten die eigendom zijn van de integratie; optionele filters projectScoutelloId en status.
GET/mail-drafts/{scoutelloId}Huidige versie, beoordelingslink, inhoudshash, goedkeurings-/verzendstatus en uiteindelijke e-mail-ID.
GET/mail-drafts/external/{externalId}Een stabiele externe ID van de integratie opzoeken.
POST/mail-drafts/batch-upsertDe voorbereiding van een concept valideren of toepassen.

Voor de voorbereiding van een concept zijn mail-drafts.write, contacts.read en projects.write vereist. Het opgegeven contact wordt een deelnemer aan het project. De goedkeurder moet een geaccepteerd organisatielid zijn met toestemming om e-mails te bewerken. De afzender wordt gekozen uit de bestaande toegestane organisatie- of persoonlijke afzenderinstellingen van dat lid; willekeurige From-adressen worden niet geaccepteerd.

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

Elke validatieresultaat controleren voordat mode: "apply" opnieuw wordt uitgevoerd. De resulterende ID uitlezen om reviewUrl, draftVersion, contentHash, status, dispatchStatus en mailScoutelloId te verkrijgen. expectedVersion: 0 uitsluitend gebruiken voor het aanmaken en voor revisies de momenteel geretourneerde versie gebruiken. Context en goedkeurder zijn onveranderlijk; beoordeelde of verzonden concepten wijzen gewijzigde inhoud af. Identieke herhaalde verzoeken retourneren het oorspronkelijke concept.

Concepten verschijnen in de e-mailtabbladen van projecten en contacten en in goedkeuringsmeldingen op het dashboard. Het voorbereiden via de API verstuurt geen e-mail, ook geen meldingsmails; bestaand gedrag voor workflow-meldingsmails blijft ongewijzigd. De toegewezen persoon kan ontvangers, onderwerp, inhoud en ondersteunde bijlagen bewerken, de versie opslaan en vervolgens Goedkeuren en verzenden. Integraties kunnen geen goedkeuring uitvoeren of verzending starten. Mislukte of onduidelijke verzendingen worden nooit blind opnieuw geprobeerd. Bij het converteren van protocolgebaseerde concepten moeten de protocollen behouden blijven en hun vervangingen naar elkaar verwijzen.

MCP-toegang​

Dezelfde Scoutello API-sleutel en scopes kunnen worden gebruikt met het MCP-eindpunt voor streamable HTTP:

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

Configureer de MCP-client om Authorization: Bearer YOUR_API_KEY te verzenden. De legacy-URL /api/mcp blijft beschikbaar als pad-alias voor compatibiliteit, maar nieuwe clients gebruiken bij voorkeur het versiegebonden eindpunt. Voormalige sctl_mcp_-inloggegevens worden niet geaccepteerd; vervang ze door een Scoutello API-integratiesleutel.

MCP-tools sluiten rechtstreeks aan op het REST-contract en gebruiken dezelfde runtime-schema's, tenantcontroles, integratielevenscyclus, limieten en servicemethoden. Zo weerspiegelen contacts_list, contacts_get, contacts_get_by_external_id en contacts_batch_upsert de vier contactroutes. Hetzelfde patroon geldt voor taken, protocollen, kansen, projecten, mijlpalen en gebeurtenissen; mail biedt mails_list en mails_get, leden bieden members_list en tags bieden tags_list.

De server maakt alleen tools beschikbaar die door de scopes van de huidige sleutel zijn toegestaan. Met contacts.read kan een sleutel de tools voor het lezen van contacten vinden, maar niet contacts_batch_upsert; een sleutel met contacts.write krijgt de tool voor batch-updates, maar niet de leestools. whoami is altijd beschikbaar. Schrijftools hebben dezelfde directe effecten als hun REST-equivalenten. Gebruik daarom mode: "validate" wanneer een aanroepende partij een batch moet inspecteren zonder deze toe te passen.

MCP werkt ook server-naar-server en maakt geen toegang vanuit browsers via andere origins mogelijk. Voor het JSON-RPC-transport is een speciale URL nodig. Daarom kan MCP geen individuele REST-resource-URL delen, ook al zijn de authenticatie en het gegevensgedrag hetzelfde.

Raadpleeg voor de volledige configuratie, verificatie, toolmapping en probleemoplossing de MCP-integratiehandleiding.

Records lezen​

Contacten, taken, protocollen, kansen, projecten, mijlpalen en gebeurtenissen gebruiken dezelfde leesroutes:

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

Vervang contacts door tasks, protocols, opportunities, projects, milestones of events voor de andere synchronisatiebronnen. externalId verschijnt in een lees-DTO wanneer het record door deze integratie is gekoppeld.

Een lijstrespons heeft deze envelop:

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

limit moet tussen 1 en 100 liggen. Resultaten worden eerst gerangschikt op het effectieve tijdstip waarop hun openbare API-weergave is gewijzigd en vervolgens op Scoutello-ID. Dit effectieve tijdstip kan later zijn dan de geretourneerde entiteit updatedAt wanneer metagegevens van de integratiekoppeling zijn gewijzigd. Cursors zijn ondoorzichtig: sla ze ongewijzigd op en verstuur ze ongewijzigd; leid geen betekenis af uit de inhoud.

De eerste respons legt snapshotAt voor die traversal vast. Volg nextCursor totdat hasMore false is, voordat een nieuwe incrementele leesbewerking wordt gestart. Zo wordt voorkomen dat records die tijdens het pagineren veranderen, de huidige traversal instabiel maken.

Verwerk voor incrementele synchronisatie elke cursorpagina en sla vervolgens snapshotAt van die traversal op als de high-watertimestamp. Geef deze bij de volgende traversal door als de updatedSince-waarde volgens ISO 8601. De ondergrens is inclusief, waardoor het opnieuw proberen van een voltooide momentopname grensrecords kan retourneren, maar deze niet kan overslaan.

Een respons voor één record heeft deze envelop:

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

Responsen voor één contact bevatten ook een relations-array. Elke relatie behoudt de Scoutello-relatie-ID, aanmaaktijd, het type, notities en de verwijzingen naar contacten connectedFrom en connectedTo. Contactverwijzingen bevatten de Scoutello-ID en de externe ID van deze integratie, wanneer die bestaat. Contacten die vanwege de privacygrens voor organisatietoegang door de API zijn uitgesloten, worden niet via relaties beschikbaar gesteld. De respons met de contactlijst blijft compact en bevat geen relaties; gebruik een van beide routes voor één contact wanneer details over relaties nodig zijn.

Werkfilters en cursorscope​

Contactlijsten accepteren search, type (person, company, supplier, other), status en tagIds. Zoektekst wordt bijgesneden, is hoofdletterongevoelig en beperkt tot 200 tekens / 10 door witruimte gescheiden tokens. Elke token moet voorkomen in ten minste één van firstName, lastName of companyName, inclusief historische bedrijfsnamen die zijn opgeslagen in lastName. Tekens zoals % en _ worden letterlijk gematcht. Tags gebruiken any-of-matching met 1–50 ID's. Alle opgegeven filters worden gecombineerd met AND. REST codeert tag-ID's als herhaalde parameters; MCP levert een array:

GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two

Contactcursors zijn gekoppeld aan de organisatie, integratie en elke filter. Behoud de filters op elke pagina; een gewijzigde filter zorgt ervoor dat de cursor wordt afgewezen. De volgorde en duplicaten van tags, evenals de volgorde, hoofdlettergebruik en witruimte van zoektokens, veranderen de effectieve filter niet.

Werkoverzicht-routes accepteren de volgende aanvullende filters; andere combinaties van resources en velden worden afgewezen:

ResourceFilters
TasksprojectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter
ProtocolsprojectScoutelloId, milestoneScoutelloId, status (draft of final)
OpportunitiesprojectScoutelloId, stage, ownerScoutelloUserId
Projectsstatus, assignedContactScoutelloId
MilestonesprojectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter

dueBefore is exclusief; dueAfter is inclusief. Ze vergelijken de vervaldatum van de taak of de einddatum van de milestone; records zonder die datum komen niet overeen. Gebruik ISO-datum-tijden met tijdzone. Alle filters worden vóór paginering toegepast. Zet een cursor voort met exact dezelfde filters, inclusief updatedSince, en dezelfde organisatie/integratie. De paginagrootte mag wijzigen. Oude cursors zonder scope moeten na deze release opnieuw worden gestart vanaf de opgeslagen high-watertimestamp.

Projects, milestones, toewijzingen en notities​

GET /members (MCP members_list) gebruikt standaardpaginering en vereist members.read. Het retourneert scoutelloId (ID van lid Customer), scoutelloUserId (ID van User) en displayName. Alleen geaccepteerde organisatieleden met een rol worden weergegeven; de zoekopdracht geeft geen e-mailadressen of machtigingen vrij.

Tasks accepteren assignedScoutelloUserIds; opportunities gebruiken ownerScoutelloUserId. Projects en milestones gebruiken assignedContacts: [{"scoutelloId":"member-customer-id"}]. Voor toewijzingen zijn geaccepteerde leden van de organisatie van de inloggegevens vereist. Weggelaten toewijzingen blijven ongewijzigd; [] verwijdert ze. Imports van projecten, milestones, taken en protocollen zijn stil: ze versturen geen meldingen of communicatie over toewijzingen.

Event assignedContacts ondersteunt leesbare CRM-contacten en geaccepteerde leden die via het Customer-ID van het lid worden aangeleverd. Geaccepteerde leden blijven niet beschikbaar als gewone CRM-contactreferenties of doelen voor externe links; gebruik het veld voor liddelen voor teamverantwoordelijkheid.

Maak mijlpalen aan met een name en projectScoutelloId of projectExternalId. Ze ondersteunen description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (standaardwaarde 0) en assignedContacts. Datums mogen niet vóór de startdatum eindigen. Elke mijlpaal heeft een stabiele externe link binnen de integratie. Het project kan niet via de API worden gewijzigd. Bij het aanmaken en bijwerken worden naam en beschrijving gelokaliseerd in de taal van de organisatie.

Taken en protocollen accepteren verwijzingen naar projecten, mijlpalen en kansen als <entity>ScoutelloId of <entity>ExternalId, bijvoorbeeld milestoneExternalId. Gebruik per relatie slechts één schrijfwijze, ook bij het wissen met null. Alle relaties moeten bij de organisatie van de referentiegegevens horen. Een verwijzing die alleen een mijlpaal bevat, leidt het project af; een conflicterend project of het expliciet wissen van een project terwijl de bijbehorende mijlpaal behouden blijft, wordt afgewezen. Een gekoppelde kans met een project moet overeenkomen met het project van het werkitem. Weggelaten relaties behouden de huidige waarden; een expliciet null wist een relatie wanneer de resterende context geldig is. In leesbewerkingen worden beide ID-schrijfwijzen en taaktoewijzingen weergegeven.

Taakplanning en workflows​

Task status is de onveranderlijke sleutel van een status in de effectieve workflow van de taak, niet een vaste enum. Lees de beschikbare organisatie- en projectworkflows met GET /task-workflows en gebruik daarbij de tasks.read-scope. Elke status bevat de sleutel, het label, de levenscyclus type (backlog, unstarted, started, completed of cancelled), de kleur, de volgorde, de standaardvlag en de archiveringsstatus. Projectvermeldingen geven aan of de organisatieworkflow wordt overgenomen. De workflowconfiguratie blijft via het dashboard beheerd.

Taken accepteren nullable priority (low, medium, high of urgent) en estimatedEffortMinutes, plus nullable startDate en dueDate. Taaklezingen bevatten de gedenormaliseerde statusType, de ouderverwijzing, compacte verwijzingen naar subtaken en verwijzingen naar blockedBy / blocks.

Maak of werk een subtasks op één niveau bij met parentTaskScoutelloId of parentTaskExternalId; null promoveert de subtask tot een taak op het hoogste niveau. Afhankelijkheden gebruiken arrays met verwijzingen naar { "scoutelloId": "..." } of { "externalId": "..." } in blockedBy en blocks. Weggelaten relatievelden behouden de bestaande relaties, terwijl een lege afhankelijkheidsarray die richting wist. De API weigert geneste subtasks, afhankelijkheden tussen ouder en kind, afhankelijkheden tussen organisaties, duplicaten, verwijzingen naar zichzelf en directe of transitieve cycli.

Filters voor de takenlijst accepteren een exacte workflowwaarde status, een levenscycluswaarde statusType, priority, parentState (top_level, subtask of parent) en blockedState (blocked, blocking of unblocked).

Protocollen accepteren daarnaast status: "draft" | "final" (nieuwe records krijgen standaard final). Voor een nieuw protocol zijn type, date en een contact of geldige project-/mijlpaalcontext vereist. contactExternalId: null wist het contact alleen wanneer de project-/mijlpaalcontext behouden blijft. Interne projectnotities kunnen daardoor worden aangemaakt en gelezen zonder een klant te verzinnen. Draft/final beschrijft de status van de notitie en verstuurt nooit een communicatie. Privétaken en -protocollen blijven ontoegankelijk.

Projectdeelnemers​

Project participants bevat additieve upserts, geïdentificeerd aan de hand van een contact-verwijzing, bijvoorbeeld:

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

Deelnemers zijn prospects/klanten die aan een project zijn gekoppeld; verantwoordelijke teamleden worden via toewijzingen vastgelegd. Weggelaten deelnemers, een lege array en weggelaten deelnemervelden behouden de bestaande gegevens. null wist role, notes of groupScoutelloId. Dubbele opgeloste contacten in één payload worden geweigerd. Groepen moeten al bij het geselecteerde project horen; leesbewerkingen bevatten participantGroups (ID/naam), deelnemer-ID's, contacten, rol, notities en groeps-ID. Deelnemers verwijderen of groepen aanmaken kan momenteel in het dashboard.

Records in batch bijwerken​

Schrijf maximaal 100 records met de batchroute van de resource:

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

Bij taakbatches worden de taakrecords eerst opgelost voordat ouder- en afhankelijkheidsrelaties worden toegepast. Dankzij deze verwerking in twee fasen kan een oudertaak, blokkerende taak of geblokkeerde taak verwijzen naar een andere taak die in dezelfde batch is aangemaakt, via het externe ID ervan, ongeacht de volgorde van de records.

Gebruik het OpenAPI-document voor de velden en validatiebeperkingen van elke resource. Elk record moet een stabiele externalId bevatten van 1 tot 200 tekens. Behandel deze als een ondoorzichtige technische identifier: gebruik geen e-mailadres, naam, API-secret of andere persoonsgegevens. externalUpdatedAt is optioneel, maar sterk aanbevolen wanneer het bronsysteem een betrouwbare wijzigingstijdstempel levert.

De request body is beperkt tot 1 MiB. mode is standaard ingesteld op apply:

  • apply valideert geaccepteerde records en schrijft deze weg.
  • validate voert dezelfde validatie en matching uit zonder gegevens weg te schrijven en retourneert would_* resultaten.

Voor contactimports kan matchByEmail in de request worden ingesteld op true. De standaardwaarde is false; de externe ID vormt de veiligere identiteitsgrens.

Weggelaten velden behouden de huidige waarde. Een expliciete null wist een nullable veld, en een meegeleverde lege toewijzings- of tagarray wist die relatie. Project participants zijn additieve upserts: een lege array laat de roster ongewijzigd. Bij het schrijven van contact-, taak-, opportunity- en eventtags worden Scoutello-tag-ID's gebruikt. Externe relatie-ID's worden uitsluitend opgelost via links die bij de huidige integratie horen, terwijl Scoutello-gebruikers-ID's voor eigenaarschap of verantwoordelijkheid moeten verwijzen naar geaccepteerde leden van de huidige organisatie.

Voor het aanmaken van opportunities is een account of contact vereist; voor verloren opportunities is ook een verliesreden vereist. Geldbedragen worden uitgedrukt in gehele centen. Namen en beschrijvingen van projecten en events worden gelezen en geschreven in de geconfigureerde taal van de organisatie. Bij het schrijven van events kunnen expliciete datums en dagelijkse, wekelijkse of maandelijkse herhaling met uitzonderingen worden opgegeven; zichtbaarheidstiers voor gepubliceerde events blijven onderworpen aan de wettelijke gereedheidscontroles van Scoutello. De API biedt geen toegang tot ticketing voor events, deelnemers, media, templates, nieuwsbrieven, samenwerkingen of andere geavanceerde functies voor eventbeheer.

Tags ontdekken​

Gebruik het tags-endpoint voordat tagIds wordt opgegeven:

GET /tags?entity=events&type=category

entity is vereist en accepteert contacts, tasks, opportunities of events. Dit wordt gekoppeld aan de overeenkomstige opgeslagen tagrelevantie. type is optioneel en accepteert category of attribute. Selecteerbare categorieën kunnen eigendom zijn van de organisatie of globaal beschikbaar zijn; selecteerbare kenmerken zijn afkomstig uit de samengestelde globale kenmerkenset van Scoutello. Resultaten bevatten scoutelloId, de naam gelokaliseerd in de organisatietaal, type en relevancy. Tag-ID's uit andere organisaties, met een onjuiste relevantie of zonder selecteerbaarheid wijzen het betreffende batchitem af.

Geschiedenis van uitgaande e-mail lezen​

De e-mailgeschiedenis is alleen-lezen:

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

Alleen organisatie-eigendom e-mail met de status sent of failed wordt geretourneerd. Reacties bevatten veelgebruikte opgeslagen headers en de berichttekst, BCC, status en tijdstempels, verwijzingen naar projecten/evenementen/nieuwsbrieven, ID's en typen van bijlagen, en geaggregeerde statistieken over aflevering, openen, klikken, bounces, klachten en afwijzingen bij ontvangers. Concepten, e-mail die in de wachtrij staat of gepland is, rijen per ontvanger, gerenderde snapshots, onbewerkte providerfouten en URL's voor het downloaden van bijlagen worden nooit beschikbaar gesteld. Een latere update over de aflevering aan een ontvanger werkt de effectieve synchronisatietijdstempel van de e-mail bij, waardoor de e-mail opnieuw in incrementele leesbewerkingen verschijnt. Er zijn geen routes voor het schrijven van e-mail.

Een toepasresultaat kan created, updated, linked, unchanged, stale_ignored of rejected zijn. Validatie maakt gebruik van would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale of rejected. Een geldig batchverzoek retourneert HTTP 200, ook wanneer afzonderlijke records worden afgewezen. Controleer daarom altijd elk item en de samenvatting van het antwoord. Vermeld het antwoord requestId wanneer ondersteuning van Scoutello wordt gevraagd een fout te onderzoeken.

Tijdstempels en conflicten​

Wanneer externalUpdatedAt aanwezig is, gebruikt Scoutello deze om verouderde wijzigingen af te wijzen zonder de rest van de batch te laten mislukken. Een resultaat stale_ignored is definitief voor die oudere payload; haal het actuele record op voordat wordt besloten een nieuwere versie te verzenden.

Behandel tijdstempels als UTC ISO 8601-waarden. Behoud hun oorspronkelijke precisie en vervang de wijzigingstijd van het bronrecord niet door het tijdstip waarop een synchronisatietaak is uitgevoerd.

Idempotentie​

De idempotentiegrens ligt bij de integratie plus externalId. Scoutello vergelijkt een canonieke payload-hash en de optionele waarde externalUpdatedAt. Daardoor ontstaan bij het opnieuw proberen van hetzelfde record geen duplicaten en kan unchanged worden geretourneerd.

Met externalUpdatedAt is dezelfde tijdstempel en payload unchanged, is een oudere tijdstempel stale_ignored en vormt dezelfde tijdstempel met een andere payload een versieconflict. Voor een koppeling die nog nooit een tijdstempel heeft geaccepteerd, blijft dezelfde payload zonder tijdstempel unchanged, terwijl een gewijzigde payload wordt toegepast in volgorde van binnenkomst. Nadat een koppeling een tijdstempel heeft geaccepteerd, wordt een gewijzigde payload waarin externalUpdatedAt ontbreekt, afgewezen als versieconflict, zodat niet-versiebeheerde gegevens de versiebeheerstatus niet kunnen overschrijven. Daarom worden wijzigingstijdstempels uit de bron sterk aanbevolen.

Audittrail​

Geaccepteerde API-aanmaak-, update- en alleen-koppelen-synchronisatieacties verschijnen in Scoutello-wijzigingslogboeken met Public API als bron en worden gekoppeld aan de verantwoordelijke integratie. Samenvattingen van operationele runs bewaren aanvraag-ID's en geaggregeerde resultaat aantallen voor probleemoplossing; recordpayloads of API-geheimen worden niet bewaard.

Fouten en nieuwe pogingen​

Fouten op aanvraagniveau gebruiken deze envelop:

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

Voer bij HTTP 429- en tijdelijke 5xx-antwoorden nieuwe pogingen uit met exponentiële back-off en jitter. Houd rekening met Retry-After wanneer deze aanwezig is. Netwerkfouten kunnen zijn opgetreden nadat Scoutello een aanvraag heeft geaccepteerd; dezelfde batch opnieuw verzenden is veilig, omdat elk record idempotent is op basis van externe ID en canonieke payload. Probeer authenticatie-, autorisatie-, validatie-, versieconflict- of afzonderlijke rejected-resultaten niet automatisch opnieuw wanneer de aanvraag niet is gewijzigd.

Aanbevolen tweerichtingssynchronisatielus​

  1. Roep /whoami aan tijdens de configuratie en controleer de verwachte organisatie en scopes.
  2. Lees elke pagina die sinds het laatste voltooide high-water mark is gewijzigd en pas die wijzigingen idempotent toe in het externe systeem.
  3. Stuur externe wijzigingen naar /batch-upsert, met stabiele externe ID's en tijdstempels van bronwijzigingen.
  4. Sla controlepunten pas op nadat alle pagina's en itemresultaten zijn verwerkt.
  5. Los conflicten op volgens de eigendomsregels van het bronsysteem; simuleer verwijderingen niet door lege records te verzenden.

Scoutello biedt in deze eerste versie bewust geen openbare verwijderroute. Handel verwijderings- of archiveringsbeleid buiten de API af totdat een gedocumenteerde levenscyclusbewerking wordt geïntroduceerd.

Sociale berichten voor menselijke beoordeling​

De sociale API bereidt berichten voor een met naam genoemde menselijke beoordelaar voor. De API kan deze niet goedkeuren of publiceren. REST en MCP gebruiken dezelfde scopes en service.

ScopeEindpunten onder /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

Nieuwe scopes moeten expliciet worden toegekend. Bestaande inloggegevens krijgen geen aanvullende toegang. Gebruik members.read om gebruikers-ID's van leden te vinden en selecteer een beoordelaar met publicatierechten (newsletter.edit). Voor concepten is geen CRM-contactpersoon of project vereist.

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

Gebruik publishMode: "now" en scheduledAt: null om na goedkeuring te publiceren. Elke kanaalvariant bevat de volledige tekst, instellingen en geordende media-ID's. Kanaaldetectie retourneert ondersteunde indelingen, limieten en instellingen. De momenteel ondersteunde kanalen zijn LinkedIn-profielen/-pagina's, Facebook, Instagram en Threads. Instagram vereist media. Een variant accepteert maximaal tien afbeeldingen of video's.

Batches accepteren maximaal 100 unieke externe ID's binnen de bestaande limiet van 1 MiB per verzoek. mode: "validate" controleert verwijzingen en versies zonder concepten op te slaan, assets te uploaden, meldingen aan te maken of werk in de wachtrij te plaatsen. Resultaten van het toepassen bevatten ID's, reviewlinks, versies en uitkomsten per record. Gedeeltelijke fouten zetten succesvolle records niet terug. Bij een fout in een melding wordt een waarschuwing met de opgeslagen review-URL geretourneerd.

Haal de huidige draftVersion op voordat een in behandeling zijnd concept wordt gewijzigd. Identieke herhalingen zijn idempotent en behouden latere handmatige wijzigingen. Reviewers kunnen niet direct worden gewijzigd. Gebruik na goedkeuring of afwijzing een nieuwe externe ID voor een nieuw voorstel. Het lezen van concepten is beperkt tot de aanroepende integratie; de publicatiegeschiedenis omvat alle opgeslagen door Scoutello gemaakte campagnes binnen de organisatie, inclusief berichten vanuit het dashboard, scripts en verouderde Scoutello-berichten. Externe kanaalgeschiedenis wordt niet geïmporteerd.

Lijsten gebruiken de standaardparameters limit, cursor en updatedSince. Berichten en concepten accepteren ook channelId, status, after, before en search; behoud alle filters op volgende cursorpagina's. Datumfilters zijn van toepassing op het publicatietijdstip (aanmaaktijdstip voor direct in behandeling zijnde concepten). Het conceptfilter status filtert op goedkeuringsstatus; status voor berichten komt overeen met een campagne- of kanaalstatus voor aflevering. Leesbewerkingen tonen de laatst bekende afleveringsstatus, fouten per kanaal, openbare links en tijdstempels van reconciliatie. Incrementele leesbewerkingen van concepten weerspiegelen ook wijzigingen in de aflevering van campagnes.

Media uploaden​

  1. Roep POST /social-media/uploads aan met clientUploadId, filename, contentType, size in bytes en de kleine hexadecimale sha256 van de oorspronkelijke bytes. Ondersteunde typen zijn PNG, JPEG, WebP, MP4, WebM, QuickTime en M4V. De uploadlimiet is 500 MiB.
  2. Verstuur de oorspronkelijke bytes met HTTP PUT naar de geretourneerde upload.url en gebruik de bijbehorende headers. Upload-URL's verlopen na 15 minuten. Gebruik clientUploadId opnieuw voor nieuwe pogingen met hetzelfde bestand; voor verlopen sessies of andere bestanden is een nieuwe ID nodig.
  3. Roep POST /social-media/uploads/{assetId}/finalize aan met een JSON-body van {}. Bij het voltooien worden de grootte, het type, de handtekening en de checksum gecontroleerd, wordt een privékopie vastgezet en wordt de asset-ID voor mediaIds geretourneerd. Herhaald voltooien is veilig.

Het uploadbeheer is gekoppeld aan de organisatie en integratie. Concepten kunnen verwezen naar voltooide assets uit hun organisatie. Voorbeeld-URL's zijn tijdelijk; haal het concept opnieuw op om ze te vernieuwen. Voor voltooide objecten worden nooit upload-URL's uitgegeven.

Menselijke beoordeling en levering​

De beoordelaar ontvangt een dashboardmelding en kan het bericht openen via Postings of de bijbehorende beoordelings-URL. Bewerken maakt een nieuwe onveranderlijke versie. Goedkeuring gebruikt de weergegeven versie en content-hash, controleert opnieuw het lidmaatschap, de kanalen en assets en maakt atomair één duurzame campagne aan. Als het voorgestelde tijdstip is verstreken, moet de beoordelaar een expliciet nieuw tijdstip opslaan of publiceren bij goedkeuring selecteren.

Bij nieuwe pogingen in de wachtrij worden de campagne en de platformontvangstbewijzen opnieuw gebruikt. Goedgekeurde campagnes kunnen niet direct worden bewerkt. Annuleren via het dashboard behoudt de goedkeuringsgeschiedenis en media; annulering kan een actieve verzending niet onderbreken. Controleer het concept of de campagne om goedkeuring te onderscheiden van daadwerkelijke platformlevering.