Team & account
API & webhooks
Let your HR, payroll and data systems create cases, send salaries and changes, and hear what happens on a case, with scoped API keys and signed webhooks.
- 1Create a keySettings → API and webhooks → New key (Admins). Name it after the system that will use it and tick only the scopes it needs: cases:read, cases:write, salaries:write, employment:write, events:read. The key is shown once: copy it into your system. Settio keeps only a fingerprint, so a lost key can't be shown again: revoke it and create a new one.
- 2Call the APISend the key as Authorization: Bearer <key>. POST /api/v1/cases (cases:write; without destinationCountry the case is in your primary country), GET /api/v1/cases/{id} (cases:read), POST /api/v1/salaries (salaries:write), POST /api/v1/employment-changes (employment:write), GET /api/v1/events?since=<cursor> (events:read). A key without the scope gets 403; an unknown or revoked key gets 401.
- 3Use Settio in an AI assistantAdd Settio as an MCP server in Claude, Cursor or another assistant that supports MCP: the address and a configuration to paste are under Settings → API and webhooks → Use Settio in your AI assistant, with your key as Authorization: Bearer <key>. The assistant acts as the person who created the key, with their role, so it can do only what they can do in Settio; give the key cases:read to look things up and cases:write to make changes too. It can list and read people, cases, steps, documents, readiness, activity and messages; create cases and add family members; update steps; add notes; send messages; request documents; record arrival and the permit; invite to the portal and mark a case ready to file. A key converted from the old single workspace key doesn't record who made it: create a new one.
- 4Add a webhookSettings → API and webhooks → Add endpoint: an HTTPS address on the public internet and the events it wants (or all). Copy the signing secret; it's shown once. Send test event checks the connection straight away.
- 5Check the signatureEach request has Settio-Signature: t=<unix time>,v1=<signature>. Compute HMAC-SHA256 of t + "." + the raw body with your secret, compare it with v1 in constant time, and refuse timestamps older than 5 minutes. The body is { id, type, createdAt, data }. The data field holds the case id (and your HR system's id for cases that came from an integration) and what changed.
- 6When deliveries failAnswer with a 2xx status within 10 seconds. Anything else is retried after 1 and 5 minutes, then 30 minutes, 2, 6, 12 and 24 hours. The last 50 deliveries show their status and answer. After 50 failures in a row the endpoint is switched off and Admins get an email. Fix it and switch it on again.
Events: case.created, case.phase_changed, case.closed, application.submitted, application.supplement_requested, application.decided, permit.recorded, permit.expiring (90 and 30 days before the end), requirement.completed, document.verified, employment.ended, monitoring.finding_opened and monitoring.finding_resolved. Names and email are only in case.created; documents are never sent.
Money: a case's salary is in the destination country's currency and period: SEK a month in Sweden, a year where a country quotes yearly salaries. POST /api/v1/cases takes salary with optional salaryPeriod (month or year) and currency (it must be the country's); GET /api/v1/cases/{id} returns currency and salaryPeriod, never the amount. POST /api/v1/employment-changes takes salary with salaryPeriod and currency, or monthlySalary as before.
Prefer polling? GET /api/v1/events returns the last 30 days, oldest first; pass the returned next as since. Events appear a few seconds after they happen, each with a stable id to dedupe on.
Practice cases send no events.
Connect Slack under Integrations to get new cases, requests for more documents, decisions, permit findings and expiring permits in a channel.
Informational only. This guide is not legal advice. Always verify requirements with official government sources before acting. About this information