De API
Er is geen privé-endpoint. Zelfs niet voor de interface.
De meeste producten hebben twee API's: de gedocumenteerde die je wordt aangeboden, en de interessante die hun eigen schermen gebruiken. De tweede is altijd beter, en jij mag er nooit dichtbij komen. Hier is er één, en de interface is er een client van zoals alles — wat een beperking voor ons is, en de reden dat alles wat jij wilt bouwen mogelijk is.
Wat die regel eigenlijk kost
Het betekent dat een scherm soms moet wachten tot de API het goed heeft, in plaats van eromheen te grijpen voor één handig veld. De dag dat een scherm iets nodig heeft wat de publieke API niet kan geven, is de dag dat de API fout is, en de oplossing is de API.
De winst is dat drie heel verschillende clients bijna niets extra's kosten. De MCP-server is een client. Een dash-b tile is een client. Je eigen script is een client. Geen van hen is een tweederangsburger die om een oppervlak heen werkt dat voor iemand anders is ontworpen, want er is geen ander oppervlak om ondergeschikt aan te zijn.
Gedocumenteerd, en gebruikt
OpenAPI wordt gegenereerd op /docs en elke route heeft een test die het voorbeeld in de documentatie is. Documentatie die los van de code wordt geschreven, schuift binnen een maand uiteen; documentatie die de build laat falen als ze fout is, niet.
Inloggen
Je castomo-account, via de authorization code flow met PKCE — hetzelfde account dat je gebruikt voor dash-b en de rest van de familie. Een pagina zonder eigen server voert die flow prima uit; daarvoor is de flow ontworpen. Voor machine-naar-machine-werk: een projectspecifieke API-sleutel.
- 1Mensen
/v1/contacts·/lists·/segments·/tags·/imports - 2Inhoud
/v1/creatives, met validatie, preview en render per doel - 3Automatisering
/v1/funnels·/funnels/:id/versions·/runs·/simulate - 4Omroep
/v1/campaigns, met doelgroep, materialiseren, plannen en verzenden als aparte stappen - 5Events binnen
/v1/events— de events van je eigen applicatie, als triggers - 6Bezorging
/sender-identities·/domains·/apps·/webhooks - 7Cijfers
/v1/reports/*, en/track/*op de tracking-host
OpenAPI op /docs/mcp op hetzelfde proces
Conventies
Dezelfde vorm als elke andere castomo-service
Dat is belangrijker dan het klinkt. Als je er al een van deze aanroept, weet je al hoe deze antwoordt, faalt en pagineert.
Eén foutenvelop
Elke fout heeft dezelfde vorm: een stabiele code en een bericht bedoeld voor een mens. Geen enkele route verzint zijn eigen manier van ongelukkig zijn.
Cursorpaginering
Geen offsets. Een lijst die verandert terwijl je hem doorloopt slaat stilletjes geen rijen over of herhaalt ze niet, wat offsetpaginering stilletjes en voortdurend wél doet.
Idempotentiesleutels
Op elke muterende route. Probeer een verzoek waarvan je niet zeker weet of het aankwam opnieuw, en je krijgt hetzelfde antwoord in plaats van een tweede contactpersoon, een tweede campagne of een tweede verzending.
Afgebakend tot een project
Een token adresseert één tenant én één project. Beveiliging op rijniveau wordt afgedwongen in de database zelf, niet door eraan te denken een clausule toe te voegen.
Webhooks naar buiten
Ondertekend, opnieuw verstuurd met backoff, en minstens één keer afgeleverd — dus jouw endpoint moet ook idempotent zijn. De events gebruiken hetzelfde vocabulaire als de rapporten.
Wissen en exporteren
Een contactpersoon kan via de API worden geëxporteerd of gewist, en een wissing bereikt elke zusterservice die een kopie had, via de interne lane van de familie zelf.
Alles wat de interface kan, kan een POST.
Events zijn het interessante deel
Alles andere op deze pagina is loodgieterswerk dat je zou verwachten. POST /v1/events is de route die verandert waar het product voor dient.
Jouw applicatie weet al dingen die geen enkele marketingtool kan waarnemen: wie de onboarding afrondde, wie een collega uitnodigde, wie een limiet raakte, wie op een zondagmiddag zijn data exporteerde. Post die als events met je eigen token, en elk ervan wordt een trigger, een voorwaarde en een segment.
De rest volgt uit het contactmodel. Events worden toegevoegd, nooit bewerkt; het is het log waar het hele product aan hangt. Een funnel die afgaat op een event dat jij hebt gedefinieerd is geen integratie — het is hetzelfde mechanisme dat message_opened gebruikt, met een andere naam erin.
- 1Je post het
POST /v1/events— een naam, een contactpersoon, een payload, een idempotentiesleutel. - 2Het landtToegevoegd aan het log van de contactpersoon. Niets anders hoeft te weten dat het bestaat.
- 3Er start een funnelElke funnel waarvan de instap dat event noemt, voor elke contactpersoon die in aanmerking komt volgens de instapspecificatie.
- 4Andere funnels takken erop af"Is dit event in de afgelopen 14 dagen gebeurd" is een gewoon segmentpredicaat.
- iEn het beëindigt runsEen doelpunt-knooppunt dat hetzelfde event noemt, stopt een sequence op het moment dat de persoon het ding doet.
Jouw vocabulaireJouw token
Grenzen die goed zijn om te kennen voordat je bouwt
ClickSomo slaat drie identificatoren over je op — een tenant, een project en een gebruiker, als ondoorzichtige ids — en niets anders. Geen wachtwoord, geen profiel, geen kaart, geen factuur. Planlimieten komen als cijfers binnen: hoeveel contactpersonen, hoeveel verzendingen, hoeveel generaties. Betalingsvocabulaire steekt die lijn in geen enkele richting over.
Jouw contacten zijn van jou. Jij bent de verwerkingsverantwoordelijke; wij zijn de verwerker. Er is geen route waarmee een ander product uit de familie je contactenlijst kan lezen of schrijven, en geen ingest-kanaal dat zo'n product kan gebruiken.
Als je dit serieus overweegt: lees /docs voordat je nog meer van deze website leest. De API is de eerlijke beschrijving van wat het product doet, en elke claim op deze pagina's verwijst naar een route of een node-type dat je daar vindt. Als het schema verandert, veranderen deze pagina's mee.