key option or store it on the account; the plugin sends it as the X-Simplesat-Token header.
Things to know before you write:
- A bad key is a 403, not a 401. Simplesat answers
403 Invalid Token.for a missing or unrecognised token on every route, and a valid key that lacks the route’s scope gets the same 403. Check the key and its scopes. The plugin treats both as auth failures. - Customer writes are upserts.
customers.createandteamMembers.creatematch an existing record onexternal_idoremailrather than always inserting, so send one of them. The schema rejects a customer with neither, because Simplesat then has nothing to match against. - A bulk write is queued.
customers.bulkanswers arequest_idand a message, not the stored records, and the work happens afterwards. - Surveys are identified by token.
surveys.emailtakes thesurvey_tokenfromsurveys.list, not the numeric survey id. - Sending a survey notifies a real person.
surveys.emailschedules an email, so it is a write. - Search and paging.
answers.searchandresponses.searchare POSTs because they take a filter list and date range, but their pages come back asnextlinks that are followed with a GET. Every list answers{ next, previous, count, results }, andnextis a path you pass back unchanged. - A
nextlink is checked before it is used. Simplesat returns a full URL, and the plugin keeps only same-host paths, so the token never travels to another host. - A response create can update.
responses.createcreates a response or updates the one that already matches it, andcreatedbackdates it, which is how a survey answered elsewhere is imported.
- 17 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Simplesat API key before the first call: More: API Key
pnpm corsair setup --plugin=simplesat --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Search responses for one customerWhat’s next
API reference
Every
simplesat.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.